Skip to content

[release/17.0] Harden Go SDK runtime and complete typed API export metadata - #22028

Closed
Mitch Denny (mitchdenny) wants to merge 1 commit into
mitchdenny-backport-17-0-30-pr21855from
mitchdenny-backport-17-0-31-pr21827
Closed

Mitch Denny (mitchdenny) wants to merge 1 commit into
mitchdenny-backport-17-0-30-pr21855from
mitchdenny-backport-17-0-31-pr21827

Conversation

@mitchdenny

Copy link
Copy Markdown
Member

Description

Backport of #21827 to release/17.0 (cherry-picked from e7ff435 with no modifications).

Layer 31 of 55 in the release/17.0 backport stack; stacked on #22027.

Backport recommendation: Yes — Fixes races and connection-wide failures in the Go SDK runtime shipped in 17.0.

Validation: Stable patch IDs match (ea8c059a5da2e6bcb2faedd49752e20283c02c25). Builds/tests not run for this unchanged cherry-pick.

Backport of #21827

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

## Description

Generated Go AppHosts can run callbacks concurrently with the main
builder chain without racing the sticky error or lazy collection
accessors. Invalid request arguments and unencodable callback results
now fail their individual calls instead of disconnecting every pending
operation. Callback decoding errors and `runtime.Goexit` produce
explicit JSON-RPC errors; message headers and cancellation requests are
bounded.

The Go API export also includes structured `type` and `optional`
metadata for every field and constant. DTO optionality comes from ATS
metadata, not the generated `omitempty` tag or pointer spelling. This is
additive to schema version 1 and includes options, runtime fields, enum
constants, and exported value leaves. Export snapshots and the
output-format documentation are updated.

Related to #21204, #21212, and #21115. This does not close either
follow-up issue. The remaining structured Kubernetes manifest work is
separate in #21824.

### User-facing usage

Collection serialization preserves its existing signature; failures are
now observable through the additive `Err` methods:

```go
payload := resource.GetTags().ToJSON()
if err := resource.GetTags().Err(); err != nil {
    return err
}
_ = payload
```

`aspire sdk export --language go --package Name@Version` now emits
fields such as:

```json
{
  "name": "Mode",
  "type": "*TestPersistenceMode",
  "optional": true
}
```

Cancellation watchers are armed only after the invocation carrying their
IDs has entered the FIFO write queue. The cancellation RPC has a
five-second timeout; a canceled call still returns through its own
context without waiting for that RPC.

### Validation

Commands ran on Windows with the restored repository SDK and an isolated
Go 1.27.3 toolchain added to `PATH`. Linux race checks used Go 1.26.10
and GCC from the existing local `aspire-go-e2e-6972:latest` image.

| Command | Result |
| --- | --- |
| `.\restore.cmd` | Passed; 17 dependency audit warnings, no errors. |
| `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"` | Passed: 130 tests, no failures or
skips. Reviewed and accepted generated Go/JSON snapshot changes. |
| `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"` | Passed after
adding the final actual-getter-failure assertions. |
| `go test -race -timeout 60s -v .` | Passed in a generated module
extracted from the Go snapshot, with `runtime_test.go`,
`transport_hardening_test.go`, and `decode_test.go` from the C# tests.
Includes a callback and main chaining on the same captured generated
builder, encoding failures, callback errors/Goexit, header bounds, and
cancellation ordering/timeout cleanup. |
| `go test -race -timeout 60s -run
TestCallbackAndMainCanChainOnCapturedBuilder .` | Failed as expected
against the original main snapshot with data races; the same regression
passes with this branch. |
| `dotnet test --project
tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | Passed: 698 tests, 1 skipped.
Includes integration scanning and Go export/codegen coverage. |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-launch-profile -- --filter-class "*.SdkExportCommandTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` | Passed: 31 tests. |
| `dotnet build src\Aspire.Cli\Aspire.Cli.csproj --configuration Release
/p:SkipNativeBuild=true` | Passed, with the existing ILCompiler audit
warning. Managed Release build, not native AOT. |
| `.\.dotnet\dotnet.exe
artifacts\bin\Aspire.Cli\Release\net11.0\aspire.dll sdk export --help` |
Passed; help lists Go as an export language. |
| `git diff --check` | Passed. |

### Remaining policy and execution gaps

- Callback registry release still needs a host release signal and a
cross-language ownership contract. This PR does not unregister callbacks
when a registration capability returns, because the host can invoke them
later.
- Disconnect-driven `os.Exit(1)` is unchanged. Choosing an observable
shutdown contract requires a cross-language decision; no GA lifecycle
guarantee is introduced.
- The reported required-token path is currently unreachable because
`SplitParameters` places all cancellation tokens in Go options. Both
token-emission paths select the supplied token's context.
- A bundled current-main CLI export measuring Redis/Azure Storage
XML-summary coverage was not run. No documentation-copy policy was
changed based solely on project-built behavior.
- No new grouped export view was introduced; consumers still have
`capabilityId` for grouping. The aspire.dev consumer and its grouping
decision are outside this product-only change.
- Native AOT publishing, the full CLI suite, a many-integration live
AppHost, polyglot E2E, macOS, and the complete CI matrix were not run.
Go feature-flag-off validation is obsolete because #21183 removed that
flag.

### Security considerations

This changes handling of AppHost JSON-RPC messages and callback
payloads. Headers are limited to 16 entries and 8 KiB before body
allocation, in addition to the existing 64 MiB body cap. Invalid typed
callback arguments are rejected before user code is called; decoding no
longer silently substitutes invalid DTO fields. No authentication,
listener, or permission policy changes are made. A formal threat
model/security review has not been performed.

## 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?
  - [x] Yes
    - If yes, did you have an API Review for it?
      - [ ] Yes
      - [x] No
- Did you add `<remarks />` and `<code />` elements on your triple slash
comments?
      - [ ] Yes
      - [x] No
  - [ ] No
- Does the change make any security assumptions or guarantees?
  - [x] Yes
    - If yes, have you done a threat model and had a security review?
      - [ ] Yes
      - [x] No
  - [ ] No

The additive APIs are Go `List.Err`/`Dict.Err` and JSON export metadata;
no public C# API was added. Go documentation comments describe the error
contract. Triple-slash XML elements do not apply to these Go members.
The fixes in this PR are complete; the explicitly deferred
cross-language policy and bundle-validation items remain tracked in the
related issues.

---------

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
(cherry picked from commit e7ff435)
@github-actions

This comment has been minimized.

@mitchdenny
Mitch Denny (mitchdenny) force-pushed the mitchdenny-backport-17-0-31-pr21827 branch 2 times, most recently from c6bb987 to 6a3a806 Compare November 10, 2026 04:24
@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 -- 22028

Or

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

@mitchdenny

Copy link
Copy Markdown
Member Author

Approved for inclusion in release/17.0. Do not merge yet.

@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.

@github-actions

This comment has been minimized.

@mitchdenny
Mitch Denny (mitchdenny) force-pushed the mitchdenny-backport-17-0-31-pr21827 branch from d0efd35 to 6a3a806 Compare November 10, 2026 06:40
@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.

@mitchdenny
Mitch Denny (mitchdenny) force-pushed the mitchdenny-backport-17-0-31-pr21827 branch from 6a3a806 to d0efd35 Compare November 10, 2026 07:39
@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants