Skip to content

Fix nil resource builder in Go AppHost callbacks - #21261

Merged
David Pine (IEvangelist) merged 1 commit into
mainfrom
ievangelist-go-callback-wrappers
Oct 28, 2026
Merged

David Pine (IEvangelist) merged 1 commit into
mainfrom
ievangelist-go-callback-wrappers

Conversation

@IEvangelist

Copy link
Copy Markdown
Member

Note

Merge order: land this PR after the other open Go generator PRs. It does not depend on any of them and is based on main, but it changes files that #21188, #21193, #21194, #21195, #21197 and #21199 also change (AtsGoCodeGenerator.cs, Resources/base.go, the Go generator tests and the two Go snapshots).

Description

In a Go AppHost, a callback whose parameter is a resource builder (Action<IResourceBuilder<T>> in C#) received a nil value, so the first call on it panicked. The host marshals callback arguments with the declared parameter type, so a closed generic IResourceBuilder<T> is sent with a closed-generic $type (Type.FullName, which embeds the assembly-qualified T), while a builder returned from a capability is sent with the plain id of T. The generated Go SDK registers wrappers only for plain ids, so the transport left the raw handle in place and callbackArg[T] fell back to the zero value of T, a nil interface.

The generated callback shim now builds the wrapper from the declared parameter type instead of relying on $type, which is what the TypeScript generator already does.

Fixes #21255

Before and after

A Go AppHost from aspire-go-empty plus Aspire.Hosting.Docker, run through aspire publish with the Go generator and runtime from main versus this branch:

env := builder.AddDockerComposeEnvironment("env")
env.ConfigureDashboard(func(dashboard aspire.DockerComposeAspireDashboardResource) {
	dashboard.WithHostPort(&aspire.WithHostPortOptions{Port: aspire.Float64Ptr(9003)})
})
Before After
Callback argument nil usable DockerComposeAspireDashboardResource
aspire publish panic: runtime error: invalid memory address or nil pointer dereference, the Go AppHost exits with status 2 and the CLI exits with code 6 exit 0, all 7 steps succeed, docker-compose.yaml maps 9003:18888 on env-dashboard

What changed

  • Go runtime (Resources/base.go): callbackHandleArg[T](c, args, idx, wrap) returns wrap(h, c) when the argument is still a raw *handle and otherwise defers to callbackArg[T], so values the transport already wrapped (plain resource and context ids) take the path they took before.
  • Generator (AtsGoCodeGenerator): a callback shim emits callbackHandleArg(s.client, args, i, new<Interface>FromHandle) for a handle-category parameter that has a generated constructor and a client in scope. DTOs, enums, CancellationToken and DTO property callbacks (which have no client) keep callbackArg[T].
  • Tests: a generator test that pins the emitted wrapper for PublishAsDockerFile, and a Go-backed test ([RequiresTools(["go"])]) that compiles the generated SDK and drives a callback over an in-memory fake host with both a closed-generic and a registered $type. Both fail on the old generator.
  • Snapshots: regenerated.

Reviewer notes

  • The snapshot diff is one mechanical transform. callbackArg[X](args, N) becomes callbackHandleArg(s.client, args, N, newXFromHandle) at 260 call sites (259 changed lines) in TwoPassScanningGeneratedAspire.verified.go and 11 call sites (10 changed lines) in AtsGeneratedAspire.verified.go, plus the 17-line helper in the latter (it embeds base.go). Applying the inverse transform to the new snapshots reproduces the files on main byte for byte. Only the four PublishAsDockerFile shims for ContainerResource (executable, dotnet tool, project and C# app) change behavior in those snapshots; every other site is a context or event type that already arrived wrapped.
  • More exports are fixed than the issue lists. Across hosting and 19 integration assemblies, 27 declared IResourceBuilder<T> callback parameters expand to 29 shims that were affected, for example WithDashboard (Docker Compose and Kubernetes), WithRedisInsight, WithPgAdmin, WithMongoExpress, WithKafkaUI and the Azure RunAsEmulator and RunAsContainer overloads.
  • Not covered.
    • ConfigureEnvFile on Docker Compose takes Action<IDictionary<string, CapturedEnvironmentVariable>> and has a related cause: its dictionary argument still arrives as a zero-value *Dict with no handle behind it, so using it panics. It is the only dictionary-typed callback parameter in the 53 generated Go validation SDKs. A small generator change that wraps it the same way worked in a local check; it is left out so this PR stays about resource builders.
    • DTO property callbacks have no client in scope; none of them takes a resource builder today.
    • Callbacks passed through an options struct (the project and C# app PublishAsDockerFile overloads, and ConfigureContainer on Redis WithRedisInsight and WithRedisCommander) panic earlier, in deepUpdate, on main with or without this change. Fix Go AppHost panic on callback options and accept Go numbers in unions #21188 rewrites deepUpdate. With a local workaround for deepUpdate, the Redis callbacks received nil before this change and a live wrapper after it; none of these overloads was run on a tree that contains Fix Go AppHost panic on callback options and accept Go numbers in unions #21188.
    • Java appears to have the same weakness (read, not run). TypeScript and Python already use the declared parameter type for the wrapper.
    • No CI job runs a Go callback at runtime: polyglot-validation.yml only compiles the Go validation AppHosts. The new Go-backed test covers the transport against an in-memory fake host.
    • Not run: Linux and macOS, aspire run with the dashboard UI (the checks below use aspire publish, and the PublishAsDockerFile callback does not run in run mode), go test -race (no C compiler on the machine), and Rust.
  • Host-side alternative not taken. Marshalling the plain resource type id would fix every guest at once, but it changes the wire contract that CallbackProxyTests pins.

Validation

Windows, Go 1.27.0, Docker 29.9.1. The dotnet test runs are on the final commit. The Go AppHost checks ran on the same change before a clean rebase onto the current main (the patch is identical).

  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.Go.Tests/Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": 35 passed, 0 failed, 0 skipped (33 on main). Run twice, and git status was clean after each run, so the snapshots are stable.
  • The same project with the old AtsGoCodeGenerator.cs and base.go under the new tests and snapshots: 4 failed (both new tests and both snapshot tests).
  • dotnet test --project tests/Aspire.Hosting.RemoteHost.Tests/Aspire.Hosting.RemoteHost.Tests.csproj --no-launch-profile -- --filter-class "*.CodeGenerationResolverTests" --filter-class "*.IntegrationLoadContextTests" --filter-class "*.ApiReferenceExportTests" --filter-class "*.ServiceErrorMessageTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" (the classes that resolve the Go generator): 27 passed, 0 failed.
  • Real Go AppHosts built with aspire new aspire-go-empty, then aspire restore and aspire publish, before and after:
    • ConfigureDashboard with WithHostPort(9003): panic and CLI exit 6, then exit 0 with all 7 steps and 9003:18888 on env-dashboard.
    • PublishAsDockerFile(func(c aspire.ContainerResource) {...}) on an executable: panic and CLI exit 6, then a live wrapper whose calls (entrypoint, environment, and WaitFor with the wrapper as an argument) all appear in the compose file.
    • 15 callbacks whose $type is a registered id (WithEnvironmentCallback, WithArgsCallback, SubscribeBeforeStart and others): the generated compose files are identical before and after.
  • All 53 Go validation AppHosts under tests/PolyglotAppHosts pass aspire restore and go build with this generator.
  • A throwaway in-package test of callbackHandleArg (not committed): 14 observations, and 64 goroutines x 2000 calls with no bad results.

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

A Go AppHost callback whose parameter is a resource builder, for example
ConfigureDashboard(func(dashboard aspire.DockerComposeAspireDashboardResource))
or PublishAsDockerFile(func(obj aspire.ContainerResource)), received a nil
wrapper and panicked as soon as it used it.

The AppHost marshals an IResourceBuilder<T> callback argument with the closed
generic CLR type as its $type. The generated SDK registers wrapper factories
only for plain type ids, so the Go transport leaves the argument as a raw
*handle. callbackArg[T] cannot turn a raw handle into a wrapper interface, so
it returned the zero value, a nil interface.

Generated callback shims now read handle arguments with callbackHandleArg,
which builds the wrapper for the declared parameter type from the raw handle,
the same way the TypeScript SDK does. Arguments that already arrive wrapped,
handle types without a generated constructor, and DTO property callbacks keep
using callbackArg. The AppHost resolves incoming handles by $handle only, so
the wrapper behaves like any other.

The two Verify snapshots are regenerated. Most of the large snapshot diff is
mechanical: every handle-typed callback shim now goes through callbackHandleArg,
and only the shims whose handle arrives under an unregistered type id (the
ContainerResource callbacks of PublishAsDockerFile) behave differently.

Tests: a generator test asserts the shim shape, and a Go test runs the
generated SDK against an in-memory fake AppHost for a closed generic $type and
for a registered $type. Both new tests fail without the change and pass with
it. The Go code generation test project passes (35 passed, 0 failed).

Also checked with a real Go AppHost that calls ConfigureDashboard and then
WithHostPort(9003) on the dashboard: aspire publish failed with a nil pointer
dereference in the callback before this change, and after it the generated
compose file maps the dashboard port as 9003:18888.

PublishAsDockerFile was checked end to end through the executable overload
(the dotnet tool overload has the same shape). The project and C# app
overloads receive the callback through PublishAsDockerFileOptions; on main
they panic earlier, in deepUpdate, before the callback is registered. That
defect is separate and is not changed here.

Fixes #21255

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@IEvangelist David Pine (IEvangelist) added area-polyglot Issues related to polyglot apphosts area-codegen labels Oct 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21261

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21261"

@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

2 / 100 PR test projects · 2 PR jobs, from 5 changed files.

Selected PR test projects (2 / 100)

Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.RemoteHost.Tests

Selected PR jobs (2)

polyglot, typescript-api-compat


How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests
→ 1 via the project graph: Aspire.Hosting.RemoteHost.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/Resources/base.go (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/AtsGoCodeGeneratorTests.cs (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/AtsGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

Job reasons

Job Triggered by
polyglot affected project Aspire.Hosting.CodeGeneration.Go
typescript-api-compat affected project Aspire.Hosting.CodeGeneration.Go

Selection computed for commit 437624e.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The focused fix preserves existing conversion paths and includes regression coverage for both raw and already-wrapped handles, with no unresolved findings.

No open issues 🎉

What changed in this PR

Fixes #21255 by making generated Go AppHost callbacks wrap raw resource-builder handles using the declared parameter type, preventing nil callback arguments without changing the host wire contract.

Changes:

  • Adds a runtime helper that constructs wrappers for raw handles while preserving existing argument conversion.
  • Updates callback generation to use the helper when a constructor and client are available.
  • Adds generator and Go-backed regression tests for raw and already-wrapped handles, and refreshes snapshots.
File Description
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​TwoPassScanningGeneratedAspire.verified.go Updates expected callback shims across hosting types.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​AtsGeneratedAspire.verified.go Updates callback shims and embedded runtime helper.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​AtsGoCodeGeneratorTests.cs Adds generated-code and callback transport regression coverage.
src/​Aspire.Hosting.CodeGeneration.Go/​Resources/​base.go Adds declared-type wrapping for raw callback handles.
src/​Aspire.Hosting.CodeGeneration.Go/​AtsGoCodeGenerator.cs Emits wrapper-aware conversions for eligible callback parameters.

Review effort: Balanced

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. Building the wrapper from the declared parameter type is the right fix, and it matches what the TypeScript generator does. The rewrap only happens when the transport left a raw *handle, so arguments that already arrive wrapped keep the old path. I also checked that undoing the transform on the new snapshot reproduces the old one, and the Go codegen tests pass locally on macOS arm64 (35/35, including the Go-backed test).

Notes:

  • main has since landed #21116, which also edits the Go snapshot. Its new callback shims take *TerminalOptions (a DTO), so this change doesn't affect them, and the branch still merges cleanly.
  • As the description says, options-struct callbacks still depend on #21188 for deepUpdate, and the conflict with #21197 in EmitDtoCallbackToMap needs the resolution described there.

The two inline comments are minor test nits. They can be follow-ups or a small update before merge.

@IEvangelist
David Pine (IEvangelist) merged commit 672179a into main Oct 28, 2026
78 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Oct 28, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

✅ No documentation update needed.

Skipped: proven false positive / bug_fix_restores_documented_behavior.

  • Triggered signals (2): polyglot_code_generator_changed (evidence: AtsGoCodeGenerator.cs, Resources/base.go) and pr_body_has_cli_flag_mention (evidence: the dotnet test --project ... validation command in the PR body, not a product flag).
  • The PR fixes a bug in the generated Go SDK, where a resource-builder callback argument was nil and caused a panic. Callbacks should receive a usable builder, so this restores intended behavior.
  • Other changed files are tests and snapshots. No new public API, option, or documented behavior changes.

David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
Resolve the conflicts with the Go generator changes that landed on main
(#21188 union and callback fix, #21199, #21261 accepting interfaces):

- AtsGoCodeGenerator.cs: keep both sets of private fields and helpers.
  BuildNameMaps builds the accepting interfaces first and the documentation
  maps last. The enum constant name comes from main's
  GetEnumMemberConstantName, the doc block and GoStringLiteral escaping stay.
  The union allowed-types doc note also reports that float64 accepts any
  built-in Go numeric type, matching main's widened type switch.
- Regenerate the three affected snapshots from the merged generator. Their
  non-comment, non-blank lines are identical to main's.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist) added a commit that referenced this pull request Oct 30, 2026
…21197)

> [!NOTE]
> **Merge order:** no PR must land before this one. #21188 and #21199,
which overlapped it, are on main and this branch contains them.
Whichever of the remaining open PRs lands second rebases:
>
> - A PR that changes `TwoPassScanningGeneratedAspire.verified.go` (a
new or changed `Aspire.Hosting` API reaches it) conflicts with this one
there, because this PR adds doc comments throughout the file. Regenerate
the snapshot with `dotnet verify accept -y` instead of merging hunks by
hand. `AtsGeneratedAspire.verified.go` works the same way.
> - #21195 calls `RenderGoExportedValueType`, whose signature this PR
changes, so the second to land needs a one-line fix-up in
`AtsGoCodeGenerator.ApiProjection.cs`.

## Description

Part of #21115.

The Go SDK generator documents a member only from the capability
`Description`, plus a few fixed comments for enums, DTOs and handles.
`Summary`, `Remarks`, `Returns`, per-parameter docs, enum value docs and
the obsolete and experimental flags never reach `aspire.go`, so `go doc`
and gopls hover show one thin line or nothing. This PR emits godoc from
the same ATS documentation metadata the TypeScript generator already
turns into JSDoc.

### What changes in the generated SDK

Documentation flows to every kind of declaration:

- Capabilities (handle methods, standalone functions, property getters
and setters): summary, remarks, a `Parameters:` list and a `Returns:`
paragraph. A trailing `...Options` parameter points at its Options
struct, and each Options field carries the doc of its parameter.
- Handle interfaces, DTO structs and their fields, enum types and each
enum value, exported value groups and their members, and Options
structs.

The comments follow godoc conventions:

- A comment starts with the identifier it documents, paragraphs are
separated by a bare `//`, and code samples and lists from the XML docs
keep an indented-block form. Lines are wrapped near 80 columns and never
split a word.
- `<see cref>` references become `[Name]` doc links only for generated
types. Anything else stays plain text so the SDK has no dangling links.
- Obsolete capabilities end with a `Deprecated:` paragraph, the one
marker gopls and staticcheck recognize.
- Experimental capabilities get a `# Experimental` heading and the line
`Notice: This API is EXPERIMENTAL and may be changed or removed in a
later release.` Go has no toolchain-recognized experimental marker, so
this uses the convention `google.golang.org/grpc` documents its
experimental APIs with. It renders as a heading on pkg.go.dev and in
gopls hover and is stable under gofmt. TypeScript uses `@experimental`.
- XML-doc text is normalized to LF and no comment line has trailing
whitespace.
- A one-line remarks paragraph that gofmt and `go doc` would read as a
heading, such as `Requires Redis 7.2` or `Used with the resource's
name`, ends with a period so it stays a paragraph.

Example from the test snapshot. On main this method has only the first
line:

```go
// WithPreviewStatus sets the preview status.
//
// Parameters:
//   - status: The status to set.
//
// # Experimental
//
// Notice: This API is EXPERIMENTAL and may be changed or removed in a later
// release.
//
// Deprecated: Use WithDocumentation instead.
WithPreviewStatus(status DocumentedStatus) DocumentedResource
```

### Commits

1. **Share the ATS version-skew probe between polyglot generators.**
`AtsTypeSystemCompatibility` (reads the experimental flag from an
`Aspire.TypeSystem` that may predate it) moves from the TypeScript
generator project to `src/Shared/CodeGeneration` and is linked into the
Go and TypeScript generator projects. The TypeScript generator only
gains a `using`.
2. **Emit godoc from ATS documentation metadata in the Go SDK
generator.** New `GoDocComment.cs` formats a comment from the metadata,
and `AtsGoCodeGenerator.cs` calls it at each declaration.
3. **Escape ATS metadata at the Go generator output sinks.** Injection
hardening, described below.
4. **Render exported string values as Go string literals.** The same
sink class for exported values, described below.
5. **End one-line remarks that gofmt would turn into headings with a
period.** See the conventions list above.
6. **Make the escaping and gofmt round-trip comments state what they
cover.** Comments only.
7. **Build the Go doc maps with the name maps.** `BuildNameMaps` builds
the documentation maps itself, so a caller that builds only the name
maps still gets a usable renderer (review feedback).

### Escape ATS metadata at the Go generator output sinks

ATS metadata (descriptions, capability ids, parameter and property
names) was spliced into Go source unescaped. A multi-line description,
or a name containing a quote, a newline or a percent sign, produced Go
that did not compile or that carried extra statements. Now:

- every doc comment line is prefixed with `//`: CR, LF and CRLF start a
new comment line, and Unicode line and paragraph separators, control
characters and the byte order mark are replaced or dropped, so a
description cannot end the comment;
- string literals (capability ids, request argument names, json struct
tags, map keys, enum constant values and `%q` arguments) go through one
`GoStringLiteral` helper, and a capability id inside a `fmt.Errorf`
format string has its `%` doubled;
- method names (`ToPascalCase`) go through the existing
`SanitizeIdentifier`, as parameter and type names already did;
- exported string values, enum values and dictionary keys go through
`GoStringLiteral` too (see the review finding below).

This is a low-severity robustness fix. An integration author already
runs code on the developer's machine, so no trust boundary is crossed.
Output for valid first-party names is unchanged: the hardening commits
change no snapshot that exists on main. The shared scanner and the other
language generators have the same pattern and are left for a follow-up.

A review of this change found one more sink of the same class, rated
Medium and fixed by commit 4. Exported string values, enum values and
dictionary keys were written with the relaxed JSON writer, which spells
a character outside the Basic Multilingual Plane (for example an emoji)
as a UTF-16 surrogate pair such as `\uD83D\uDE00`. Go rejects surrogate
halves in a string literal, so one such value failed `go build` for the
whole SDK with `escape is invalid Unicode code point U+D83D`. These
values now go through `GoStringLiteral`, which keeps such characters as
UTF-8. Numbers and booleans are the same text in JSON and Go and render
as before.

### Generated output and cost

- Two-pass SDK (`aspire.go` for `Aspire.Hosting` plus the test types):
1,347,950 to 1,808,456 bytes (+34.2%) and 31,892 to 45,393 lines. The
smaller test-types snapshot: 162,529 to 176,209 bytes (+8.4%) and 4,591
to 5,049 lines.
- The sequence of non-comment, non-blank lines in both large snapshots
is identical to main (27,526 and 3,730 lines compared, 0 differences).
The snapshot diffs are doc comment lines and the blank lines that
separate them.
- Markers in the two-pass snapshot: `Deprecated:` 16, `# Experimental`
221, `Parameters:` 848, `Returns:` 789.
- Generation time, scan excluded, 1 warm-up and 15 samples on a shared
developer machine: median 16.0 ms on main and 104.2 ms with this change
(+88 ms), min 12.8 ms and 85.7 ms. This was measured before main's
latest Go generator changes were merged and not repeated. The cost is
linear in the number of documented identifiers and the regular
expressions are source-generated. It was not profiled further.

Review tip: read `DocumentedMetadataGeneratedAspire.verified.go`,
`EscapedMetadataGeneratedAspire.verified.go` and
`GoDocCommentRender.verified.txt` first. The two large snapshot diffs
are comments only.

### Tests and guard

New tests are in `GoDocCommentTests.cs` and
`GoGeneratorEscapingTests.cs`. They build their metadata in code, so the
TypeScript `TestTypes` that the Go, Java, Python and Rust test projects
link are untouched.

- `GenerateDistributedApplication_WithDocumentedMetadata_EmitsGodoc`
(Verify snapshot) covers every declaration kind above, including
`Deprecated:`, `# Experimental`, enum values, special characters and
CRLF input.
- `Render_FormatsGodocBlocks` (Verify snapshot) covers the comment
formatter, and `Render_KeepsEveryLineInsideTheComment` proves hostile
text never leaves the `//` comment.
`Render_EndsHeadingLookingRemarksWithAPeriod` proves that one-line
remarks which `go/doc/comment` would read as a heading (gofmt rewrites
them to `# Heading`) end with a period.
- `GeneratedSdk_DocCommentsFollowGodocConventions` is the guard that
documented APIs keep their docs: over the SDK generated from the real
scanned `Aspire.Hosting` assembly, every commented declaration starts
with its name, no line has trailing whitespace or a lone CR,
`Deprecated:` starts its own paragraph, obsolete and experimental
metadata present in the model reaches the output, and the documented
enum values equal the commented constants. The two-pass snapshot also
covers the whole SDK, so an XML-doc edit to a scanned `Aspire.Hosting`
API changes it, the same coupling the TypeScript snapshot has.
- `GeneratedSdk_PassesGoToolchainChecks` runs `go build ./...`, `go vet
./...` and `gofmt` on that SDK and asserts gofmt leaves the generated
top-level doc comments unchanged. go/printer only reformats doc comments
that start in column 1, so the indented interface-method and
struct-field comments are covered by the heading test above instead.
- `GoGeneratorEscapingTests` generates an SDK from hostile metadata: a
description of `Adds Foo.\nfunc init() {}\n// ` that tries to end the
comment and declare a function, capability ids, method, parameter and
property names containing double quotes, percent signs, backslashes,
hyphens and line separators, and exported values (a string, an enum
value and a dictionary key) containing an emoji. It checks the Verify
snapshot, that no injected statement appears in the output, and that the
output passes `go build` and `go vet`. With the escaping commit's
generator changes reverted, all three fail (the injected statement is in
the output, the snapshot differs and `go build` reports syntax errors).
With only the exported-value rendering reverted, the snapshot differs
and `go build` reports `escape is invalid Unicode code point U+D83D`.

The Go toolchain tests use the existing `[RequiresTools]` gate, like
`GeneratedTransport_SupportsDuplexCommunication`, so this PR adds no
test project, CI job or runtime dependency.
`eng/github-ci/test-trigger-map.yml` needs no entry: the moved file is a
linked `src/Shared` file, which the selector attributes to its consuming
projects, and the Python, Java and Rust generators and tests do not
reference it (see the `SelectTests` row below).

### Merging with the Go API reference exporter

#21195 adds the Go API reference exporter to the same project. At its
current head (`ec5022d3a9`) the two pull requests merge without textual
conflicts (checked with `git merge-tree`), but the exporter calls
`RenderGoExportedValueType`, which this change gives a required
`includeDocs` parameter, so whichever merges second needs a one-line
fix-up in `AtsGoCodeGenerator.ApiProjection.cs`: in
`ProjectExportedValues`, pass `includeDocs: false` to
`RenderGoExportedValueType`. The compiler flags that call.

`BuildNameMaps` builds the documentation maps itself, so the exporter's
`BuildApiModel` can render documentation without any change.

The exporter's `GoApiExportTests.GoOnlySurface` snapshot then shows the
ATS documentation summaries in place of the generated `X represents X.`
text. A trial merge of both heads with that fix-up built, and 80 of the
81 tests in the Go codegen test project passed. The one failure was that
snapshot, which differed only in those summaries and is re-accepted with
`dotnet verify accept -y`. That trial ran at earlier heads of both
branches (see Not verified).

### Merge with main

This branch merges main (`45de07f9e3`), which now contains #21188,
#21199 and #21261. The conflicts were in `AtsGoCodeGenerator.cs` and two
snapshots, and the resolution keeps both sides:

- Both sets of private fields and helpers are kept. `BuildNameMaps`
builds the accepting interfaces from #21199 first and the documentation
maps last, because the renderer resolves type names through the maps
built before it.
- The enum value constant takes its name from
`GetEnumMemberConstantName` (#21199), with this PR's value doc block and
string-literal escaping.
- DTO callback conversion keeps this PR's escaped map key together with
the updated `EmitGoCallbackShimBody` call from #21261.
- The union allowed-types note now also says that `float64` accepts any
built-in Go numeric type, matching the widened type switch from #21188.

The snapshots were regenerated, not merged by hand. In the two large
ones the non-comment, non-blank lines are identical to main's (see the
counts above).

## Validation

Run from the repository root on Windows after `restore.cmd`, with Go
1.27.0 installed so the `[RequiresTools]` tests ran and were not
skipped.

| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 79 passed, 0 failed, 0
skipped (65 on main) |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 153 passed, 0 failed, 0
skipped (153 on main) |
| `dotnet run --project tools/SelectTests -- --from upstream/main --to
HEAD --explain` | 0 | 0 unattributed changed files, no fallback. Selects
7 of 100 PR test projects: `Aspire.Cli.EndToEnd.Tests`,
`Aspire.Cli.Tests`, `Aspire.Hosting.CodeGeneration.Go.Tests`,
`Aspire.Hosting.CodeGeneration.TypeScript.Tests`,
`Aspire.Hosting.Native.Core.Tests`, `Aspire.Hosting.RemoteHost.Tests`,
`Aspire.Managed.Tests`, and triggers the `cli-starter-validation`,
`extension-e2e`, `homebrew-installer`, `polyglot`,
`typescript-api-compat`, `typescript-sdk` and `winget-installer` PR
jobs. The Python, Java and Rust codegen test projects are not selected.
|

Not verified:

- The `polyglot` job and the full CI matrix. Of the selected test
projects, only the Go and TypeScript codegen projects and the code
generation classes of `Aspire.Hosting.RemoteHost.Tests`
(`CodeGenerationResolverTests`, `ApiReferenceExportTests` and
`ServiceErrorMessageTests`, 22 tests) were run locally. CI is the first
run for the rest.
- Whether the CI runners that run the Go test project have `go` on
`PATH`. The three toolchain tests depend on `[RequiresTools]`.
- That the generated SDK body is gofmt-clean. It is not clean on main
either, so only the comments are gofmt-checked.
- Generation time was measured once on a shared, busy machine, with main
and this change measured at different times.
- The checks that the new tests fail without each fix were run before
the two merges of main into this branch (`f06f16b7bf` and `45de07f9e3`)
and were not repeated.
- The Python, Java and Rust codegen test projects (29, 71 and 26 tests)
passed on an earlier head of this branch and were not re-run after the
exported-value and heading fixes. They do not link the moved shared file
or any file those fixes changed.
- The merge with #21195 was built and tested locally at its head
`7e3948ad85` and an earlier head of this branch only, in the Go codegen
test project and not in the full CI matrix. At its current head
`ec5022d3a9` only the textual merge was checked. #21195 may change
before it lands.

### Follow-up issues

- Escape ATS metadata in the shared scanner and the TypeScript, Python,
Java and Rust generators.
- Go SDK: package doc, standard generated-code header, gofmt-clean body,
LF output.
- Scanner: preserve `<para>` boundaries and code indentation.
- Go SDK: guard names derived with `ToCamelCase` (implementation names,
list and dictionary getter fields, builder and application
implementations) against Go keywords, and make `ReserveName` reject
keywords and predeclared names.

## Checklist

- Is this feature complete?
  - [ ] Yes. Ready to ship.
  - [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] Yes
  - [ ] No
- Did you add public API?
  - [ ] Yes
    - If yes, did you have an API Review for it?
      - [ ] Yes
      - [ ] No
- Did you add `<remarks />` and `<code />` elements on your triple slash
comments?
      - [ ] Yes
      - [ ] No
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [ ] Yes
    - If yes, have you done a threat model and had a security review?
      - [ ] Yes
      - [ ] No
  - [x] No

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-codegen area-polyglot Issues related to polyglot apphosts

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Go AppHost: callbacks that take a resource builder receive nil and panic

3 participants