Skip to content

Harden the Go runtime transport and decode lists of handles - #21194

Merged
David Pine (IEvangelist) merged 7 commits into
mainfrom
ievangelist-go-runtime-hardening
Oct 28, 2026
Merged

David Pine (IEvangelist) merged 7 commits into
mainfrom
ievangelist-go-runtime-hardening

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Description

This fixes three groups of problems that came out of the Go AppHost GA review. Two are in the embedded Go runtime (Resources/transport.go and Resources/base.go) and one is in the wrapper registration that the Go code generator emits (AtsGoCodeGenerator.cs).

  • A panic inside a callback terminated the whole Go AppHost process, and the transport trusted several values that come from the AppHost server: the frame length, handle envelopes and JSON-RPC error objects.
  • decodeAs could not decode a list or a map of handles, so calls such as GetResources() and GetChildren() returned an error instead of the resources.
  • registerWrappers in the generated SDK registered no wrapper for an interface type that gets only a marker interface, such as IResource. A handle tagged with one of those types reached the caller as a raw *handle, which no marker interface accepts, so GetResources() and FindResourceByName could not return a Resource.

Part of #21115.

No exported Go identifier was added, removed or renamed, and no wire format changed. The new error type is unexported, so callers reach Code() and Data() with errors.As and a small interface.

Transport hardening

A panicking callback now fails only that call, a bad frame or handle returns an error instead of panicking or allocating without limit, and the JSON-RPC error code reaches the caller. Each claim from the review was checked against the tree before anything was changed.

# Claim Verdict Change
1 A panicking callback is not recovered and kills the process Real recover() in the goroutine that runs the callback. The AppHost server gets a JSON-RPC error with code -32603 and the message Callback execution failed: <panic value>. The stack trace is never sent
2 Cancellation ids (ct_<UnixNano>) can collide, and every token parks a goroutine Real The id comes from a per-client atomic counter. The watcher is a context.AfterFunc that is stopped when the capability call returns, unless the token was already canceled: then the watcher still notifies the AppHost server
3 Content-Length is unbounded, negative or overflowing Upper bound real. Negative and overflow not real A frame above 64 MiB (the same cap as the generated Python runtime) is rejected before the body is allocated. strconv.Atoi already fails on overflow and length <= 0 was already rejected
4 Unchecked type assertions on wire values Real, in wrapIfHandle only Comma-ok assertions that return a descriptive error. The other wire assertions were already checked
5 extractResult drops the JSON-RPC error code and data Real The returned error is an unexported *rpcError with Error(), Code() int and Data() any
6 client.mu is held across the dial Real connect releases the lock around the dial and checks again afterwards. If a concurrent connect won, the extra connection is closed
7 The callback registry is never cleaned up By design None. The AppHost server sends no release signal for a callback and the generated onDisconnect exits the process, so the registry cannot outlive the connection
8 The sticky err on handles can race with callbacks Documented contract A doc comment on handleWrapperBase. A lock on setErr and Err() alone would be incomplete because generated code reads .err directly

Lists and maps of handles

decodeAs[T] returned raw.(T) when the value already had the right type and otherwise converted it with one JSON round trip. The transport turns every handle envelope in a result into a wrapper value, including the ones inside a list or a map, so a list of handles reaches decodeAs as a []any of wrappers. That is not a []Resource, and encoding/json cannot fill an interface element from an object, so every non-empty list of handles failed, including a list of one:

json: cannot unmarshal object into .0 of type aspire.Resource

An empty list and a single handle with a registered wrapper outside a list worked. The Go sample audit counted 184 of the 205 decodeAs[[]X] call sites in the generated SDK as lists with interface elements: DistributedApplicationModel.GetResources(), Configuration.GetChildren(), about 180 AzureResourceInfrastructure.Get<X>s() getters and 3 PipelineStep lists. The polyglot fixture (tests/PolyglotAppHosts/Aspire.Hosting/Go/apphost.go) discards these values, so CI never ran the path.

decodeAs now decodes slices and string-keyed maps one element at a time (decodeInto in Resources/base.go). An element that is already assignable to the element type, such as a handle wrapper, is stored as it is. Any other element is decoded with a JSON round trip of that element alone. Nested lists and maps recurse once per level of the target type, and everything else keeps the previous path. A failure names the element, for example aspire: cannot decode element 1 of []aspire.Resource: json: cannot unmarshal number into Go value of type aspire.Resource, where it used to be an unnamed JSON error.

Handles tagged with a marker-only interface

The AppHost server tags a handle with the declared type of the value a capability returns, so the handles from GetResources() (IResource[]) and FindResourceByName (IResource?) carry the IResource type id. For an interface type with no generated wrapper type behind it, the generator emits only a marker interface (type Resource interface { handleReference }), and registerWrappers registered no wrapper for its type id. wrapIfHandle returned the raw *handle for such a handle. A raw *handle does not satisfy Resource, so neither call could return a Resource, however a list of them is decoded.

registerWrappers now registers a bare wrapper (newHandleWrapperBase) for the type id of every marker-only interface. The TypeScript SDK registers a wrapper for the IResource type id too. The bare wrapper satisfies every marker interface, because a marker only embeds handleReference. A $type that is neither registered nor a marker-only interface still comes back as a raw *handle: callbackHandleArg relies on that for closed generic IResourceBuilder<T> ids, and the list decoder names the element when it cannot store such a handle.

Behavior notes

  • Error() on a host error returns the same text as before. A host error with an empty message now reads AppHost returned a JSON-RPC error (code N) instead of an empty string.
  • The callback error carries the panic value formatted with %v. The stack trace is neither sent nor printed. The TypeScript runtime also reports only the message of a thrown callback.
  • Canceling a token after the capability call it was passed to has returned no longer notifies the AppHost server, like the TypeScript runtime. The cancellation id is still an opaque ct_ string (ct_<counter>_<unix ms>).
  • A capability can also keep the token after the call, such as a generated property setter (SetCancellationToken(&SetCancellationTokenOptions{Value: tok})). The AppHost server keeps that token registered after the call returns, but the watcher is detached when the setter returns, so a later tok.Cancel() does not cancel the stored token. This is intended and matches the TypeScript and Java runtimes, which remove their cancellation listener in a finally after invokeCapability. Keeping a stored token cancelable would be a change in those runtimes as well, not a Go-only fix.
  • A call that returns because its own token was canceled still notifies the AppHost server. The watcher is detached only for a token that is still live.
  • A list of handles decodes without any JSON. The test allows at most 10 allocations for 100 handles. A list whose elements need a conversion, such as numbers into []int, takes one small JSON round trip per element.

Follow-ups

Not in this PR. Proposed issue titles:

  • Go runtime: make the handle-wrapper sticky error race-free (generated code reads .err directly)
  • Go runtime: List, Dict and callbackArg swallow marshal errors
  • Go runtime: bound the header count and header size in readMessage like the Python runtime (16 headers, 8 KiB)
  • Go runtime: callback registry grows without a host release signal
  • Go runtime: os.Exit in the generated onDisconnect
  • Go runtime: a pre-canceled token races its cancelToken notification against the capability request
  • Go runtime: the cancelToken request is sent with context.Background()
  • Go codegen: a required CancellationToken parameter registers the token but leaves ctx := context.Background(), so a cancel does not unblock the local call
  • Go runtime: a callback that calls runtime.Goexit never answers the AppHost server
  • Go tests: share one go process runner across the runtime test facts
  • Go polyglot fixture: assert non-empty GetResources(), GetChildren() and Azure infrastructure list results

Validation

Run on the PR head (3fd6c76041), which includes main at 672179a9b0. The red/green experiments for the transport and list changes below were run on an earlier head, five commits on main (5ea175ce62). The red/green experiment for the marker-only interface wrappers was run on the PR head.

Command 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" 67 passed, 0 failed, 0 skipped (40.8 s)
gofmt -l src\Aspire.Hosting.CodeGeneration.Go\Resources\transport.go src\Aspire.Hosting.CodeGeneration.Go\Resources\base.go no output
go vet src\Aspire.Hosting.CodeGeneration.Go\Resources\transport.go src\Aspire.Hosting.CodeGeneration.Go\Resources\base.go exit 0, no findings

The new GeneratedRuntime_PassesGoRuntimeHardeningTests writes the generated runtime for an empty model to a temp directory, adds transport_hardening_test.go and decode_test.go, and runs go test on it. The 19 Go tests are hermetic and fast. The transport tests drive the real client against a fake JSON-RPC host over net.Pipe, and each read and write by the fake host has its own 10 s deadline:

  • a panicking callback is answered with a -32603 error and the process survives
  • a callback argument with a malformed handle is answered with an error
  • cancellation ids are unique across concurrent tokens, a token does not park a goroutine, canceling a token while its call is in flight returns context.Canceled, sends cancelToken with the registered id and releases the registration (2000 passes, with no locking in the test), and canceling a token after its capability call returned sends nothing to the AppHost server
  • an oversized, overflowing, negative, zero or non-numeric Content-Length is rejected without a large allocation
  • wrapIfHandle reports a malformed handle instead of panicking
  • the JSON-RPC error code and data survive extractResult, and the code survives a request round trip (ping) over the fake host
  • a list of handles (one, several, with a null element), a map of handles, nested lists and maps, lists of values, an empty list and a nil result decode, and a decode error names the element that failed
  • a single handle and a DTO decode as before, and decoding 100 handles does not go through JSON

The fact uses the same [RequiresTools(["go"])] gate as the existing GeneratedTransport_SupportsDuplexCommunication.

GeneratedRuntime_DecodesResourcesTaggedWithTheDeclaredInterface generates the SDK from the test types and Aspire.Hosting, adds declared_interface_test.go and runs go test on it. Its two Go tests connect the real generated registerWrappers to a fake AppHost server over net.Pipe. The fake answers getResources and findResourceByName with handles tagged with the IResource type id, and the tests assert non-nil Resource values with the right handle ids. The envelope shape comes from reading the server's marshalling code, not from a captured AppHost session.

The verified Go snapshots embed the generated code, so both are refreshed. The changed lines of AtsGeneratedAspire.verified.go are the transport.go and base.go changes plus 6 marker wrapper registrations. The changed lines of TwoPassScanningGeneratedAspire.verified.go are 16 marker wrapper registrations.

Red/green for the transport changes: with Resources\transport.go restored from main, GeneratedRuntime_PassesGoRuntimeHardeningTests fails. The command was dotnet test --project tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-method "*.GeneratedRuntime_PassesGoRuntimeHardeningTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true", and the result was 1 failed (1.2 s) because the Go tests no longer build (c.cancellationsMu undefined, undefined: maxMessageSize, assignment mismatch: 2 variables but wrapIfHandle returns 1 value). A compile failure does not show the behavior, so two fixes were also removed one at a time from a scratch copy of the fixed runtime and run with go test -timeout 30s transport.go base.go transport_hardening_test.go:

Removed from the fixed runtime Result
the recover() in handleCallbackRequest FAIL, panic: boom and the test process dies
the 64 MiB check in readMessage FAIL, TestReadMessageRejectsInvalidContentLength: Content-Length "67108865": allocated 67121408 bytes before rejecting the frame, then a makeslice panic

Red/green for the cancellation race: with only Resources\transport.go restored from the commit before the fix, the same --filter-method command fails with 1 failed (9.8 s) in TestCancellationDuringCallReturnsNotifiesHostAndReleasesRegistration, for example pass 623: the host was not told about the cancellation: read pipe: i/o timeout. The race needs real parallelism, so it was also measured on a scratch module with LF copies of the runtime and the two Go test files. 40 runs of that test (2000 passes each) failed on the old runtime 0 times with 1 CPU, 33 times with 2, 40 with 4 and 39 with 8 (go test -cpu, with the old runtime's 5 s read deadline cut to 1 s so failing runs finish sooner). The fixed runtime failed 0 of 30 runs at each of the four settings.

Red/green for the list decoding: with Resources\base.go reverted to the version before the list change, the same command fails with 1 failed (4.4 s), among others:

decode_test.go:99: one handle: json: cannot unmarshal object into .0 of type aspire.decodeTestResource
decode_test.go:191: map of handles: got map[], json: cannot unmarshal object into Go struct field .a of type aspire.decodeTestResource
decode_test.go:220: list of lists: got [], json: cannot unmarshal object into .0.0 of type aspire.decodeTestResource
decode_test.go:323: decoding 100 handles allocated 523 times, want a handful

Red/green for the marker-only interface wrappers: with the marker wrapper registration removed from AtsGoCodeGenerator.cs, dotnet test --project tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-method "*.GeneratedRuntime_DecodesResourcesTaggedWithTheDeclaredInterface" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" fails with 1 failed (5.6 s):

declared_interface_test.go:67: GetResources failed: aspire: cannot decode element 0 of []aspire.Resource: json: cannot unmarshal object into Go value of type aspire.Resource
declared_interface_test.go:83: FindResourceByName failed: aspire: Aspire.Hosting/findResourceByName returned unexpected type *aspire.handle

With the registration in place, the same command passes (1 passed, 6.9 s).

Not verified

  • go test -race. The race detector needs cgo, which is not set up on this Windows machine.
  • A real Go AppHost end to end, including the list decoding and whether the AppHost server cancels an in-flight call when it receives cancelToken. The tests use a fake AppHost server over net.Pipe. The list-decoding tests use a stand-in handle interface, and the failure messages in the list-decoding experiment name decodeTestResource. Only the IResource test uses the generated Resource type, with envelopes shaped from reading the server source and not captured from a running AppHost. The 184 of 205 count comes from the sample audit of the generated SDK and was not recounted.
  • The in-flight cancellation test only catches the old behavior with 2 or more CPUs (see the red/green numbers above), so a single-CPU runner would not catch a regression.
  • The polyglot fixture still discards the list results, so CI still does not execute the generated list getters against a real AppHost server. Only GetResources() runs, against the fake AppHost server in the IResource test. Strengthening the fixture needs a locally generated SDK, which was not built here.
  • List elements that are DTOs holding handle-typed fields, and handles whose $type has no registered wrapper and is not a marker-only interface. They now fail with an error that names the element, but they were not exercised against real server data.
  • Item 6 (releasing client.mu around the dial) was checked by reading the code only, because openConnection cannot be replaced in a test.
  • A callback that calls runtime.Goexit still never answers the AppHost server, because recover() does not see Goexit.
  • Anything other than Windows with Go 1.27.0.
  • The full CI matrix, including the polyglot validation job. CI is the first run there.

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

- Recover a panicking user callback and answer the AppHost with a -32603
  "Callback execution failed: <message>" error, like the other runtimes,
  instead of terminating the process. The stack trace stays in the process.
- Give cancellation tokens a per-client counter ID so two tokens created in the
  same clock tick cannot share an AppHost CancellationTokenSource, and detach
  the watcher with context.AfterFunc when the capability call returns instead
  of parking a goroutine per token.
- Reject a Content-Length above 64 MiB before allocating the body.
- Return an error for a handle envelope whose $handle or $type is not a string
  instead of panicking.
- Keep the JSON-RPC error code and data on the error extractResult returns;
  callers reach them with errors.As and Code() int / Data() any.
- Release client.mu while dialing the AppHost.
- Document that handle wrappers are unsynchronized.

The verified Go snapshot embeds the runtime, so it is updated with it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Add GeneratedRuntime_PassesGoTransportHardeningTests, which runs hermetic Go
tests over net.Pipe against the embedded runtime:

- a panicking callback is answered with a -32603 error and the process survives
- a callback argument with a malformed handle is answered with an error
- cancellation IDs are unique across concurrent tokens, a token does not park a
  goroutine, and its watcher is detached once the capability call returns
- an oversized, negative, zero or malformed Content-Length is rejected without
  a large allocation
- wrapIfHandle reports a malformed handle instead of panicking
- the JSON-RPC error code and data survive extractResult and sendRequest

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
decodeAs[T] decoded a slice or a map through one JSON round trip, which
cannot produce interface elements. wrapIfHandle replaces the handle
envelopes in a result with wrapper values, so every non-empty list of
handles failed with "json: cannot unmarshal object into .0 of type
aspire.Resource". That covers Model().GetResources(), GetChildren(), the
PipelineStep lists and the AzureResourceInfrastructure getters.

Slices and string-keyed maps are now decoded one element at a time. An
element that is already assignable to the element type, like a handle
wrapper, is stored as is, and only the other elements take a JSON round
trip. A failure names the element index or the map key and the target
type. Single values, DTOs and []byte keep the previous path.

The Go tests live in the runtime hardening fact, now named
GeneratedRuntime_PassesGoRuntimeHardeningTests, and the verified Go
snapshot is refreshed because it embeds the runtime.

Part of #21115

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@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 -- 21194

Or

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

@github-actions github-actions Bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Oct 20, 2026
@github-actions

This comment has been minimized.

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.

🔵 Needs a closer look

Connection-lifecycle concurrency remains unvalidated, and in-flight cancellation cleanup lacks focused regression coverage.

1 open issue
What changed in this PR

Hardens the embedded Go runtime for Go AppHost GA and enables decoding collections of resource handles.

Changes:

  • Adds callback panic recovery, transport validation, structured errors, and cancellation cleanup.
  • Decodes handle lists and maps element by element.
  • Adds runtime regression tests and refreshes the generated snapshot.
File Description
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​AtsGeneratedAspire.verified.go Updates the embedded runtime snapshot.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​AtsGoCodeGeneratorTests.cs Adds transport and collection-decoding tests.
src/​Aspire.Hosting.CodeGeneration.Go/​Resources/​transport.go Hardens callbacks, messages, errors, and connection handling.
src/​Aspire.Hosting.CodeGeneration.Go/​Resources/​base.go Supports handle collections and documents wrapper concurrency limits.

Review effort: Balanced

Cover the path generated code takes when the call context is token.Context(): the call returns context.Canceled, the host receives the cancelToken request, and the cancellation registration is released afterwards. The test cancels while holding the registry lock so the returning call cannot stop the watcher before the cancellation has started it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Canceling a context closes its Done channel before it starts the goroutines
of the AfterFunc watchers registered on it. A call that runs on a token's
own context returns as soon as Done is closed, and releaseCancellations
then stopped the watcher before the cancel had started it, so the AppHost
never received cancelToken and its operation kept running.

The registry now stops the watcher only while the token is still live. A
call that returns because of the cancel leaves the watcher to notify the
host, and a token canceled after the call returned still sends nothing.

The in-flight cancellation test cancels without holding the registry lock
and repeats the race 2000 times, because a single pass loses the
notification in well under 1% of runs. The snapshot embeds the runtime and
is regenerated.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@github-actions

This comment has been minimized.

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.

🔵 Needs a closer look

Transport lifecycle and cancellation concurrency changes warrant human review because race-detector and real-AppHost validation remain outstanding.

1 open issue

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.

Thanks, this is a careful and well-scoped hardening pass. I checked each transport claim against the code and found no blocking problems, so I'm approving. The items below are minor and can be handled as follow-ups or as small updates before merge.

  • Race-detector run: I ran the embedded Go tests (transport_hardening_test.go, decode_test.go) against the generated runtime with go test -race on macOS arm64 (Go 1.26.2). They pass with -count=3, and the cancellation tests also pass with -count=5 -cpu 1,2,4,8. That covers the "not verified: go test -race" item in the description. Aspire.Hosting.CodeGeneration.Go.Tests also passes 34/34.
  • Cancellation token passed to a setter (inline comment on invokeCapability): could you add a line to the PR description confirming that this is intended and matches the TypeScript runtime?
  • Pre-canceled token: context.AfterFunc on a context that is already done fires right away, so cancelToken(id) can reach the AppHost before the capability request. The server's CancellationTokenRegistry.GetOrCreate then creates a fresh CTS for that id that is never canceled. This was already the case before the PR and is in your follow-up list. I'm mentioning it only to note that the server-side cancellation is lost in that case; the local ctx still unblocks the caller.
  • In-flight cancellation test: as the description notes, it only catches the old behavior with 2 or more CPUs. That's fine for CI runners today. A test seam that delays the AfterFunc goroutine would make it deterministic later.
  • Merge order with #21188: both PRs add tests at the same place in AtsGoCodeGeneratorTests.cs and change AtsGeneratedAspire.verified.go, so whichever lands second needs a rebase and dotnet verify accept -y.

David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
…every resource (#21193)

## Description

A freshly scaffolded Go AppHost had several rough edges: the SDK that
the CLI regenerates under `.aspire/` was not ignored by git,
`apphost.go` was not gofmt-clean, the scaffold output, the `go-starter`
template and the generated SDK files took CRLF line endings on Windows,
the launch profile ports came from a range that overlaps the Windows
dynamic port range, 49 sample AppHosts used a `log.Fatalf` call that `go
vet` rejects, and the starter's `builder.Err()` check could not see a
failed `AddRedis` or `AddGoApp`.

- **Ignore the generated SDK.** `GoLanguageSupport.Scaffold` now also
writes a `.gitignore` containing `.aspire/`, where the CLI regenerates
the SDK (`.aspire/modules`; it is large and rebuilt from the AppHost's
integrations). The `go-starter` template gets the same one-line file,
like the TypeScript, Python and Java starters, and
`TemplateGitIgnoreTests` has a `go-starter` row. In a directory that
already has a `.gitignore`, `ScaffoldingService` keeps it and appends
only the missing entries (`MergeGitIgnoreContent`).
- **gofmt-clean `apphost.go`.** The scaffold listed `"log"` before
`"apphost/modules/aspire"` in one import group, which gofmt reorders,
and ended without a final newline, which gofmt adds (a C# raw string
literal drops the last newline). It now has two import groups and ends
with a newline.
- **LF line endings at the source.** gofmt rewrites a CRLF `.go` file,
and three producers wrote CRLF on Windows. The scaffold's string
literals take the line endings of the C# source (`apphost.go`, `go.mod`,
`apphost.run.json`). The `go-starter` template is embedded and
scaffolded exactly as it is checked out. The generated SDK files
(`go.mod`, `transport.go`, `base.go`, `aspire.go`) mix raw string
literals, `StringWriter` output and embedded resources. `Scaffold` now
converts every file it returns to LF, `GenerateDistributedApplication`
replaces CRLF with LF at its single exit point, and `.gitattributes`
pins `*.go` and the `go-starter` directory to LF. The generator replaces
only `\r\n`: `ReplaceLineEndings` would also split at U+2028, form feed
and NEL, which Go allows inside comments and strings, and the generated
doc comments carry the description text of the exported APIs.
- **Launch profile ports.** `apphost.run.json` drew four ports from
`random.Next(10000, 65000)`, which overlaps the Windows dynamic port
range (49152-65535). It now uses `AppHostProfilePortGenerator`, which
the CLI templates and the TypeScript scaffold already use. Its fixed
ranges all end below 22300 (dashboard 15000-15299 http and 17000-17299
https, OTLP 19000-19299 and 21000-21299, resource service 20000-20299
and 22000-22299). The shared file is linked into the Go code generation
project.
- **Sample AppHosts pass `go vet`.** 408
`log.Fatalf(aspire.FormatError(err))` calls in 49
`tests/PolyglotAppHosts/*/Go/apphost.go` files became
`log.Fatal(aspire.FormatError(err))`. `go vet` reports `non-constant
format string in call to log.Fatalf` for the old form, and a `%` in an
error message would be printed as a formatting verb. The edit is one
token per line with line endings and BOMs unchanged, and no
`Fatalf(aspire.FormatError` remains in the tree.
- **Playground comment.** The example comment in
`playground/GoAppHost/apphost.go` said `AddRedis("cache", nil, nil)`,
which no longer matches the generated signature, where optional
parameters are a trailing options struct. It now says
`AddRedis("cache")`.
- **Check every resource handle.** A child-returning call such as
`AddRedis` or `AddGoApp` that fails records its error on the handle it
returns, not on the builder, and `Build()` checks only the builder's own
error, so the `builder.Err()` check in the template could not see it.
The `go-starter` `apphost.go` now keeps the `api` handle and checks
`Err()` on `cache` and `api` before `Build()`. The `aspire init` example
comment shows the same loop, with `AddRedis` and `AddPostgres`. The
template has no `{{token}}` placeholders, so `aspire new
aspire-go-starter` writes this file as it is, and the `apphost.go` on
the Go AppHost page in microsoft/aspire.dev#1924 is the same text.
- **Tests.** `GoScaffoldTests` (new, 15 test cases) covers the exact
scaffold file set, LF line endings of the scaffold output and of the
`go-starter` files, a `.gitignore` that ignores only `.aspire/`, the
`go.mod` module, go, require and replace directives, the launch profile
ports staying inside the shared generator ranges (five port seeds,
including `null`), language detection on the scaffolded files, and
gofmt-cleanliness of the scaffold output and of the `go-starter` sources
as checked out. `AtsGoCodeGeneratorTests` gets
`GenerateDistributedApplication_WritesFilesWithLfLineEndings`. The Go
code generation test project links every `go-starter` file as a test
input, plus the shared `TemporaryWorkspace` helper. No
`eng/github-ci/test-trigger-map.yml` change is needed:
`tests/PolyglotAppHosts/**` already routes to the polyglot job, the
`go-starter` files are a `None Include` that the project graph sees, and
`.gitattributes` already routes to every target, so this PR selects
every test target. The handle check has no test of its own: nothing pins
the content of the starter `apphost.go` or of the `aspire init` comment,
and `ScaffoldedAndStarterSources_AreGofmtClean` covers their formatting.

Part of #21115

### Not in this PR

- Making the generated SDK (under `.aspire/modules`) gofmt-exact. About
30 emit sites write single-line blocks such as `if x != nil { ... }`,
struct and const alignment differs, and the imports are space-indented,
so `gofmt -l` lists the file. It is git-ignored and regenerated on every
restore, and fixing it means changing those emit sites and re-accepting
every generated-SDK snapshot.
- Running `go vet` over the sample AppHosts in CI.
- The `experimentalPolyglotGo` header comment in
`playground/GoAppHost/apphost.go`, which goes away with the feature flag
(#21106).

## Validation

Commands ran on Windows from the worktree root, on top of
`upstream/main` `5ea175ce62` at head `de7b79d7d2`, with the repo-local
SDK.

| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-restore --no-launch-profile -- --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 49 passed,
0 failed, 0 skipped |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-restore --no-launch-profile -- --filter-class
"*.TemplateGitIgnoreTests" --filter-class "*.NewCommandTests"
--filter-class "*.NewCommandTemplateConfigPersistenceTests"
--filter-class "*.ScaffoldingServiceTests" --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 165
passed, 0 failed, 0 skipped |
| `git grep -n "Fatalf(aspire.FormatError" HEAD` | 1 | no match (`git
grep` exits 1 when nothing matches) |

The Go run includes all of `GoScaffoldTests`. A `--list-tests` check
showed the Cli run includes the new `go-starter` row of
`TemplateGitIgnoreTests`.

Test-first check for the scaffold LF change: the two new tests
`Scaffold_WritesFilesWithLfLineEndings` and
`ScaffoldedAndStarterSources_AreGofmtClean` were run on their own, in a
CRLF working tree, against the scaffold as it was before the
`ReplaceLineEndings` line was added (the other changes already in
place). Both failed (2 run, 2 failed). The first reported `apphost.go`,
`go.mod` and `apphost.run.json` as containing CR. The second reported
`gofmt -l` listing the scaffolded `apphost.go` with a whole-file diff.
With the change both pass. This also shows that the gofmt test really
runs gofmt when the tools are present. Running `gofmt -d` (Go 1.27.0) on
a minimal file with the previous single import group, and on one without
a final newline, confirms the other two fixes: gofmt moves
`"apphost/modules/aspire"` above `"log"` and adds the missing final
newline.

Test-first check for the starter and generator LF change:
`GoStarterFiles_UseLfLineEndings` and
`GenerateDistributedApplication_WritesFilesWithLfLineEndings` were run
on their own against the source without this change, in a CRLF working
tree. Both failed (2 run, 2 failed). With the change both pass, as part
of the 49 above. Negative control: with the two new `.gitattributes`
rules removed and the starter files re-created,
`GoStarterFiles_UseLfLineEndings` and
`ScaffoldedAndStarterSources_AreGofmtClean` failed again (the second
with a gofmt diff of `go-starter/api/main.go`). With the rules restored
and the files re-created, `git ls-files --eol` lists all 8 starter files
as `i/lf w/lf attr/text eol=lf` and every test passes. The gofmt test
now reads the starter files exactly as they are checked out, without
converting them first.

`ScaffoldedAndStarterSources_AreGofmtClean` is marked
`[RequiresTools(["go", "gofmt"])]`. When a tool is missing the attribute
adds the `category=failing` trait, and the CI test runner filters that
trait out (`eng/Testing.targets`), so the test is left out there rather
than failed. `GeneratedTransport_SupportsDuplexCommunication` in the
same project already works this way with `[RequiresTools(["go"])]`. The
two new LF tests need no external tool and run everywhere.

`go vet` over the 53 sample AppHosts (Go 1.27.0). The first run
generated one SDK from the union of all the samples' packages (80
packages) with a locally built Debug CLI and vetted every sample against
it.

- Before the change: 4 clean, 32 `non-constant format string in call to
log.Fatalf`, 17 type errors.
- After the change: 36 clean, 0 format string failures, the same 17 type
errors.
- The 17 type errors appear only in the shared SDK. Each of those 17 was
vetted again against an SDK generated from only its own packages (in a
scratch copy of `tests/PolyglotAppHosts/<Sample>/Go`: `aspire restore
--non-interactive --apphost apphost.go`, then `go vet ./...`): 17 of 17
clean.
- The scaffolded `apphost.go` with its `go.mod`, and the `go-starter`
AppHost, were vetted the same way and also build with `go build ./...`
(exit 0).

The CLI for these runs was a locally built Debug CLI from an earlier
`main` (`3ed7e9690b`) plus an unrelated Go `aspire docs api` commit, not
a build of this branch's base. The five commits between that `main` and
`5ea175ce62` touch neither the Go or TypeScript code generators, the
shared code generation, the type system, the remote host, nor any Go
sample. These runs also predate the LF commits and the rebase onto
`5ea175ce62`; none of them changes the content of the samples or of the
generated SDK, only its line endings.

Handle check and end-to-end runs (head `de7b79d7d2`). The first checks
used a generated SDK that has `AddRedis`, `AddGoApp` and `AddPostgres`,
from an earlier CLI build (this PR does not touch those APIs or
`Resource.Err()`). The `go-starter` `apphost.go` with its `go.mod`
builds and vets (`go build`, `go vet`, Go 1.27.0, both exit 0) and
`gofmt -l` lists nothing. The `aspire init` example comment, uncommented
in a scratch `main.go` with a `[]aspire.Resource{cache, db}` slice, also
builds and vets, and it is the text of the `Scaffold` raw string with
the comment markers removed (compared as strings). The `apphost.go`
fence on the Go AppHost page in microsoft/aspire.dev#1924 is
byte-identical to the template once line endings are normalized.

Then I built the CLI from this head and ran it on Windows (a Debug build
that targets net11.0, run as `dotnet aspire.dll` with the repo-local
runtime; Go 1.27.0 with `GOTOOLCHAIN=local`, `GOWORK=off` and
`GOPROXY=off`). The Go starter is still behind
`features__experimentalPolyglotGo` until #21106 lands, so I set it.
`aspire new` needed `--version 17.0.0-dev`: without it the CLI looks for
a local `Aspire.ProjectTemplates` package of its own version and finds
none.

- `aspire new aspire-go-starter --version 17.0.0-dev --name verifygo
--non-interactive --suppress-agent-init` exited 0. The `apphost.go` it
wrote is byte-identical to the template (1224 bytes, LF only, no BOM),
`.gitignore` is exactly `.aspire/`, and all 8 starter files have no CR.
In that project `gofmt -l` lists nothing, and `go build ./...` and `go
vet ./...` exit 0 against the SDK the command generated.
- `aspire init --language go` in an empty directory exited 0 and wrote
`.gitignore` (`.aspire/`), `apphost.go` with the new handle-loop
comment, `go.mod` and `aspire.config.json`. The Go files and
`.gitignore` have no CR and no BOM, `gofmt -l` lists nothing, and `go
build ./...` and `go vet ./...` exit 0. `aspire.config.json` has CRLF on
Windows because `AspireConfigFile.Save` uses the platform newline for
every language; this PR does not change that.
- A failed `Add` call at run time. In a copy of the starter I renamed
the Go app to `"cache"`, the name of the Redis resource, so `AddGoApp`
fails on the server (`Cannot add resource of type
'Aspire.Hosting.Go.GoAppResource' with name 'cache' because resource of
type 'Aspire.Hosting.ApplicationModel.RedisResource' with that name
already exists`). With the new loop, `aspire run --apphost apphost.go
--isolated --non-interactive` stopped before `Run()`, printed that
message and `exit status 1`, and the CLI reported `The Go apphost
failed`. In a second copy that skipped the loop and wrote the results to
a file, `builder.Err()` was nil, `cache.Err()` was nil, `api.Err()` held
that message and `Build()` returned nil, so a check of `builder.Err()`
alone does not see the failure.

Overlap with open PRs: this PR shares files with #21183
(`playground/GoAppHost/apphost.go`), #21187 (`GoLanguageSupport.cs`),
#21188 (`AtsGoCodeGenerator.cs`, `AtsGoCodeGeneratorTests.cs`), #21194
(`AtsGoCodeGeneratorTests.cs`), #21195 and #21197
(`AtsGoCodeGenerator.cs`, `Aspire.Hosting.CodeGeneration.Go.csproj`) and
#21199 (`AtsGoCodeGenerator.cs`). A trial merge (`git merge-tree
--write-tree`) of this head with the head of each of those seven PRs
(`0e65752d44`, `e1bb4c11ae`, `9088dfe7fb`, `ffc59f2023`, `7d33810c11`,
`82a44b0723`, `4f5a7a84aa`) was clean, as was a trial merge with each of
the other open Go AppHost PRs and with `upstream/main` `f4ae2cc424`.

Not run:

- `aspire init --language go` in a directory that already has a
`.gitignore` or a `go.mod`. The run above used an empty directory. The
`.gitignore` merge has two unit tests
(`MergeGitIgnoreContent_AppendsMissingEntriesWithoutOverwritingExistingContent`
and
`MergeGitIgnoreContent_DoesNotAddDuplicateAspireEntryWhenEquivalentEntryAlreadyExists`).
- The LF changes are observable only on CRLF inputs. On a Linux or macOS
checkout the LF tests pass with or without them, and I ran on Windows
only. A working tree checked out before the `.gitattributes` rule keeps
CRLF in the `go-starter` files, because git does not rewrite existing
files when an attribute changes, so `GoStarterFiles_UseLfLineEndings`
fails there until the files are re-created (delete the `go-starter`
directory and run `git checkout -- <directory>`). Fresh checkouts are
not affected. Whether the official build checks the `go-starter` files
out as LF or CRLF was not checked; the rule makes it LF either way.
- The rest of `Aspire.Cli.Tests`, the CLI end-to-end tests, and the
polyglot validation scripts under
`.github/workflows/polyglot-validation`. `test-go.sh` there scaffolds
with `aspire init --language go` and inserts code before the
`builder.Build()` line; the scaffold keeps that line and both imports.
- `go vet` over the 53 sample AppHosts with a CLI built from this head.
Only the starter and the `aspire init` scaffold were run with it.
- The output of the 36-sample union SDK vet run was not saved to a file,
so only the per-sample runs above can be repeated from the description.

## Checklist

- Is this feature complete?
  - [x] Yes. Ready to ship.
  - [ ] 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
David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
…ons (#21188)

> [!NOTE]
> **Merge order:** no PR must land before this one. It overlaps two open
PRs, and whichever lands second rebases:
>
> - #21194 adds tests at the same place in `AtsGoCodeGeneratorTests.cs`.
> - #21197 changes the union helpers next to `GetUnionAllowedTypes` in
`AtsGoCodeGenerator.cs` and two snapshots. Keep both sets of helpers and
re-accept the snapshots with `dotnet verify accept -y`.

## Description

A Go AppHost that passes an options struct holding a callback panics
when the options are merged, for example `AddManifestOptions{Configure:
...}` from #18080:

```
panic: aspire: merge error: unexpected end of JSON input
```

Every generated Go method that takes `...*XxxOptions` merges its options
with `deepUpdate` before serializing them. `deepUpdate` merged through a
JSON round trip and discarded the marshal error. `encoding/json` cannot
marshal a `func` value, even a nil one, so any options struct with a
callback field failed, and `*CancellationToken` (`json:"-"`) was
silently dropped. This is not specific to `AddManifest`: the same path
breaks every Configure-style option in the generated SDK (Kubernetes
`AddManifest` and `WithHelm`, the Azure Container Apps and App Service
`PublishAs*` options, `InteractionProgressOptions` and the validation
callbacks). The polyglot validation job only `go build`s those fixtures,
so none of these paths was ever executed.

- **`deepUpdate` merges by reflection** (`Resources/base.go`). Struct
fields and map entries present on both sides merge recursively. Any
other value, including nil, is taken from the later option, as before. A
struct with unexported fields (such as `*CancellationToken`) is opaque
and is taken whole. Neither argument is modified. For a small options
struct this is about 6-15x faster than the JSON round trip, with about
10x fewer bytes and 17-33x fewer allocations (Go 1.27 micro-benchmark).
- **Go numeric values are accepted by number unions**
(`AtsGoCodeGenerator.cs`). Go boxes the constant `3` as `int`, but the
generated union guard for a parameter that allows an ATS number only
accepted `float64`, so `WithField(path, 3)` failed with `parameter
"value" must be one of [string, float64, bool], got int`. The type
switch now accepts every Go numeric type when `float64` is a union
member. They all serialize as JSON numbers. Without this the publish in
#18080 could not set an integer such as `maxReplicaCount: 3`, even after
the panic was fixed.

Part of #18080. This fixes Bug 1 only, so it does not close the issue.

### Not in this PR

Bug 2 of #18080 (`WithField` only accepts scalar values and dot-notation
paths, so nested specs and keys that contain dots, such as
`app.kubernetes.io/component`, cannot be expressed) is not Go-specific.
`KubernetesManifestResource.WithField` is limited by
`[AspireUnion(string, double, bool)]`, which the server enforces for
every language, while `NormalizeManifestValue` already handles arrays
and objects. The proposal is to drop the union so `value` is `any`, with
an additive `withFieldJson(path, json)` overload as the fallback. That
is an API-shape decision for every polyglot SDK and needs API review and
a dispatch test, so it is left out here.

### Behavior notes

- A later option's nil field still overwrites an earlier non-nil value.
This is unchanged.
- A nil map now stays nil. The JSON round trip turned it into an empty
map.
- The merged result can share a map with one of its inputs when the
other side is nil.
- Named numeric types such as `time.Duration` are still rejected by the
union guard. Only the predeclared numeric types are accepted.

## Validation

| Command | Result |
| --- | --- |
| `.\restore.cmd` | passed |
| `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"` | 34 passed, 0 failed, 0 skipped |

The new `GeneratedRuntime_PassesGoTests` writes the generated runtime to
a temp directory, adds Go tests for the merge semantics and the numeric
union guard, and runs `go test` on it. It uses the same
`[RequiresTools(["go"])]` gate as the existing
`GeneratedTransport_SupportsDuplexCommunication`. A Go-only test export
(`GoTestExtensions.cs`, `WithScalarField`) exercises the union guard
through the real generator. Two Verify snapshots are refreshed.

Red/green: with the generator from before this change,
`GeneratedRuntime_PassesGoTests` fails with 11 rejections of `got int`.

End to end with a real Go AppHost, using a Debug-built CLI with
`ASPIRE_REPO_ROOT` pointing at this branch. The AppHost calls
`AddManifest` with a `Configure` callback that sets a label, an
annotation, a string field and `WithField("spec.maxReplicaCount", 3)`:

| Runtime | Result |
| --- | --- |
| This branch | `aspire publish` exits 0 with 10/10 pipeline steps and
writes `templates\kube-service\scaler.yaml`, a `keda.sh/v1alpha1`
`ScaledObject` with the label, annotation and `maxReplicaCount: 3` as an
integer |
| `base.go` from before this change | `panic: aspire: merge error:
unexpected end of JSON input` from `deepUpdate` via `AddManifest`, "The
connection to the AppHost was lost", `aspire publish` exits 6 |

Not verified:

- Python, Java and Rust callback options. They were read from snapshots
only.
- The polyglot validation job and the full CI matrix. CI is the first
run there.

## Checklist

- Is this feature complete?
  - [x] Yes. Ready to ship.
  - [ ] 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
David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
> [!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).
>
> - When this PR was opened it merged cleanly (`git merge-tree`) with
every other open Go AppHost PR except #21197. The one conflict is two
lines in `EmitDtoCallbackToMap`: keep #21197's `GoStringLiteral(...)`
line and this PR's `clientExpression: null` argument.
> - If the Go snapshots conflict or go stale after another PR lands,
regenerate them by running the Go codegen test project twice, because
Verify rewrites the snapshots on the first run.
> - #21188 also rewrites `deepUpdate`, which fixes the options-struct
panic described under "Not covered".

## 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:

```go
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. #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 #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?
  - [x] Yes. Ready to ship.
  - [ ] 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
Keep both Go runtime test methods in AtsGoCodeGeneratorTests.cs: GeneratedRuntime_PassesGoTests and GeneratedRuntime_PassesGoRuntimeHardeningTests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment has been minimized.

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.

🟡 Changes recommended

Nonempty GetResources() results still fail because declared-interface handles lack a compatible Resource wrapper, while the cancellation test risks spurious timeouts from an unrefreshed write deadline.

2 open issues
1 resolved since last review

Review effort: Balanced

The AppHost tags each handle with the type its capability declares, so an IResource[] result carries the IResource type id on every element. Marker-only interface types have no generated constructor, and without a registered wrapper the transport hands back a raw handle that no marker interface accepts, so GetResources() and FindResourceByName() fail against real server data.

registerWrappers now registers a bare handle wrapper for each marker-only interface type id, as the TypeScript SDK does, so those handles decode into the marker interface. A regression test drives the real generated registrations with IResource-tagged envelopes.

The runtime hardening test's fake host refreshes its read and write deadlines per operation instead of relying on one deadline set when the host is created, so a slow runner cannot expire it mid-run.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

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

Selected PR test projects (4 / 100)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests, 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)
→ 2 directly: Aspire.Cli.Tests, Aspire.Hosting.CodeGeneration.Go.Tests
→ 1 via the project graph: Aspire.Hosting.RemoteHost.Tests

📦 affected project Aspire.Hosting.CodeGeneration.Go
→ 1 test: Aspire.Cli.EndToEnd.Tests

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

🔧 src/Aspire.Hosting.CodeGeneration.Go/Resources/transport.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 3fd6c76.

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

No active review issues block the Go AppHost runtime hardening and collection-decoding changes.

1 open issue
1 resolved since last review

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@IEvangelist
David Pine (IEvangelist) merged commit f956911 into main Oct 28, 2026
329 of 332 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

Pull request created: #1972

Generated by PR Documentation Check · copilot · auto · 26 AIC · ⌖ 1.14 AIC · ⊞ 7.1K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#1972 targeting release/17.0.

Updated app-host/go-apphost-conventions.mdx for the Go runtime changes. Triggered signals: polyglot_code_generator_changed (AtsGoCodeGenerator.cs, transport.go, base.go) and pr_body_has_cli_flag_mention. The page now covers JSON-RPC error Code() and Data() through errors.As, callback panic isolation (-32603), lists of handles returned as aspire.Resource, and cancellation after the call returns.

Note

This draft PR needs human review before merging.

Karol Zadora-Przylecki (karolz-ms) pushed a commit that referenced this pull request Nov 3, 2026
…ntimeHardeningTests (#21474)

## Description

Removes the flaky Go runtime test
`TestRegisterCancellationDoesNotParkGoroutinePerToken` from the script
that `GeneratedRuntime_PassesGoRuntimeHardeningTests` runs. This follows
review feedback: we don't need a goroutine-count test for this.

### Why
The test compared the process-wide `runtime.NumGoroutine()` before and
after registering 1000 cancellation tokens. That count includes
goroutines the test doesn't own (runtime/GC workers, goroutines from
earlier tests still exiting), so on a busy runner it went over its
50-goroutine limit without any leak. Example: [run
41074175594](https://github.com/microsoft/aspire/actions/runs/41074175594),
Windows, first attempt, `registering 1000 tokens left 1222 more
goroutines running`.

**Frequency:** since the test landed in #21194, it failed in 1 of 128
first-attempt `Hosting.CodeGeneration.Go` jobs (1/64 on Windows, 0/64 on
Ubuntu). Locally it failed 8 of 900 runs under CPU stress.

An earlier revision of this PR deflaked it by counting live goroutines
from a stack dump. Per review, this PR now removes the test instead.

### Scope
- Only that one Go test function is removed (11 lines).
- The other generated-runtime hardening tests in
`GeneratedRuntime_PassesGoRuntimeHardeningTests` are unchanged,
including cancellation ID uniqueness, cancellation notification and
malformed frames/handles.
- No product code changes.

### Validation
`Aspire.Hosting.CodeGeneration.Go.Tests` (`AtsGoCodeGeneratorTests`)
passes locally: 40/40, including
`GeneratedRuntime_PassesGoRuntimeHardeningTests` with Go installed.

## Checklist

- Is this feature complete?
  - [x] Yes. Ready to ship.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [ ] Yes
  - [x] No (test-only removal)
- Did you add public API?
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [x] No
- Does the change require an update in our Aspire docs?
  - [x] No

**🤖 Posted by AspireAgent (AI Agent)**

---------

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist) added a commit that referenced this pull request Nov 5, 2026
> [!IMPORTANT]
> **Merge last.** This PR depends on the other open Go AppHost PRs and
must land after them.
>
> - **Must land first**, because each adds references to the flag that
this PR has to delete: #21189 (E2E helper and call sites), #21195
(`SdkExportCommandTests`) and #21196 (`GoAppHostToolingCheck` and its
tests).
> - **Must land first**, because it edits the same hunk of
`DefaultLanguageDiscovery.cs` and this PR rebases onto it: #21191.
> - **Should land first**, because removing the flag turns Go on for
everyone and these fixes should ship before it: #21186, #21187, #21188,
#21193, #21194, #21197 and #21199.

## Description

Removes the `experimentalPolyglotGo` feature flag so Go AppHosts are
available by default, the same way TypeScript AppHosts are. With no
flag, **Empty (Go AppHost)** and **Starter App (Go API + Redis, Go
AppHost)** are offered by interactive and non-interactive `aspire new`,
and Go is offered by `aspire init` language selection and `--language
go`.

**This is the GA switch for the Go AppHost epic (#21115) and must merge
last**, after the other children have landed: #21108 (E2E, publish,
deploy), #21110 (support policy, API review, packaging), #21112 (docs
and samples) and #21114 (VS Code debugging). It was opened as a draft so
CI exercises the 52 Go fixtures without the flag. It is ready for review
now, but not for merging.

What changed:

- **CLI:** `KnownFeatures` drops the Go flag and
`DefaultLanguageDiscovery` no longer marks Go experimental.
`LanguageInfo.IsExperimental` is kept because Python, Java and Rust
still use it.
- **Leftover key:** a stale `experimentalPolyglotGo` in a user's
configuration is ignored with no warning, matching what happened to the
TypeScript flag when it was removed. `Features` only reads named keys,
and the extension schemas set `additionalProperties: false`, so VS Code
flags the stale key.
- **Extension schemas:** `aspire-config`, `aspire-global-settings` and
`aspire-settings` are regenerated with
`extension/scripts/generate-schema.js`. Only the 16-line Go block is
removed from each.
- **Fixtures and CI:** 52
`tests/PolyglotAppHosts/*/Go/aspire.config.json` files and
`.github/workflows/polyglot-validation/Dockerfile.golang` no longer set
the key.
- **Java E2E picker offsets:** Go is always listed now, so with only the
Java flag set the `aspire init` language picker is C#, TypeScript, Go,
Java, and Java needs 3 Down presses instead of 2. The first CI run on
this PR timed out waiting for `> Java` in `JavaPolyglotTests`,
`JavaCodegenValidationTests` and `JavaPolyglotApphostDirectoryTests`;
each now presses Down once more, with a comment stating the picker
order. The order comes from `DefaultLanguageDiscovery`,
`LanguageService` and `CliTemplateFactory`. TypeScript flows are
unaffected because TypeScript sorts before Go.
- **Tests:** `DefaultLanguageDiscoveryTests`, `NewCommandTests`,
`ConfigCommandTests`, `NewCommandTemplateConfigPersistenceTests` and
`InitCommandTests` now expect Go without the flag, with 6 new tests. One
of them, `GetAvailableLanguagesAsync_ListsLanguagesInPickerOrder`, pins
the picker order so a future ungated language fails a unit test before
it breaks a Docker E2E run.
- **Docs:** `docs/specs/polyglot-apphost.md`, the Go code generation
README and `playground/GoAppHost/apphost.go` no longer mention the flag.

Fixes #21106

## Validation

| Command | Result |
| --- | --- |
| `.\restore.cmd` | passed |
| `dotnet build
tests\Aspire.Cli.EndToEnd.Tests\Aspire.Cli.EndToEnd.Tests.csproj -m:2
--no-restore` | 0 warnings, 0 errors |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-launch-profile -- --filter-class "*.DefaultLanguageDiscoveryTests"
--filter-class "*.NewCommandTests" --filter-class "*.ConfigCommandTests"
--filter-class "*.NewCommandTemplateConfigPersistenceTests"
--filter-class "*.InitCommandTests" --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 312 passed, 0
failed (run before the picker-order test was added) |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-launch-profile -- --filter-class "*.DefaultLanguageDiscoveryTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` | 39 passed, 0 failed (38 existing plus the
picker-order test) |
| `node extension\scripts\generate-schema.js` | only the Go block was
removed from each schema |
| repository-wide search for `experimentalPolyglotGo` and its variants |
0 hits |
| JSON parse of the 53 fixtures and 3 schemas | all parse, none contain
the flag |

Run in PR CI instead of locally, all passing on `0e65752d44`: the three
Java E2E tests (`JavaPolyglotTests`, `JavaCodegenValidationTests` and
`JavaPolyglotApphostDirectoryTests`; they need Docker, so CI was the
first execution of the extra Down press), `Infrastructure.Tests` and the
VS Code extension unit and E2E jobs.

Not run: the VS Code new-project flow in an extension host
(`extension/src/commands/new.ts` just runs `aspire new`).

### Before merging

- [ ] Search again for `experimentalPolyglotGo`,
`KnownFeatures.ExperimentalPolyglotGo`,
`EnableExperimentalGoSupportAsync`, `features__experimentalPolyglotGo`
and `experimentalPolyglot:go`, because open Go branches add flag setup
of their own and this PR must merge after all of them. Today that covers
#21189 (the `EnableExperimentalGoSupportAsync` helper and its call sites
in every Go scenario), #21195 (`SdkExportCommandTests` sets
`KnownFeatures.ExperimentalPolyglotGo`) and #21196
(`GoAppHostToolingCheckTests` builds its language discovery with the
flag, including a `goEnabled: false` case that stops being meaningful,
and `GoAppHostToolingCheck` has a comment that describes the flag). Each
of them stops compiling or goes stale once the flag is removed, so
delete or rewrite them here.
- [ ] Rebase onto #21191, which adds `DefaultHostingPackages =
["Aspire.Hosting.Go"]` to Go's `LanguageInfo` in the same hunk of
`DefaultLanguageDiscovery.cs` (#21045). Keep that initializer and drop
`IsExperimental: true`.
- [ ] Drop the Go experimental notes in the aspire.dev API reference and
docs at the same time.

## 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

needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants