Repository navigation
Make generated Go SDK APIs idiomatic - #21976
Conversation
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21976Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21976" |
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical defects can corrupt 64-bit results, produce uncompilable or incomplete Go APIs, break scaffolded AppHosts, and allow metadata to inject executable code.
8 open issues
Declaration scanner drops synthesized application interfaces · New Empty generated types cause an out-of-range slice · New Exported option interfaces are missing their bodies · New Go starter still uses option structs that no longer compile · New Unsanitized parameter names can inject code through comments · New Stripping With can make the only option constructor unexported · New Generated option names can collide and break compilation · New JSON decoding loses precision for 64-bit integer results · New
What changed in this PR
This PR makes Aspire’s generated Go SDK more idiomatic by formatting generated source, preserving CLR numeric types, and replacing pointer-based capability options with typed functional options.
Changes:
- Formats generated Go files with
gofmt, UTF-8 encoding, and LF line endings. - Introduces semantic numeric mappings and functional-option interfaces and constructors.
- Updates API export projection, focused tests, and generated snapshots for the new API shape.
| File | Description |
|---|---|
src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.cs |
Adds formatting, numeric mappings, and functional-option generation. |
src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.ApiProjection.cs |
Projects option interfaces and constructors into API exports. |
src/Aspire.Hosting.CodeGeneration.Go/GoApiModel.cs |
Updates options-model documentation. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/AtsGoCodeGeneratorTests.cs |
Tests numeric mappings and functional-option generation; adapts formatting assertions. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/AtsGoDerivedBuilderTests.cs |
Updates derived-builder expectations for functional options and formatting. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/GoApiExportTests.cs |
Updates API-export assertions for option interfaces and constructors. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/AtsGeneratedAspire.verified.go |
Refreshes generated SDK formatting, numeric types, and options. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/DocumentedMetadataGeneratedAspire.verified.go |
Refreshes documented signatures and optional DTO wrappers. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/EscapedMetadataGeneratedAspire.verified.go |
Refreshes escaped-metadata output and option constructors. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoApiExportTests.AugmentingPackage.verified.json |
Updates package augmentation signatures and numeric fields. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoApiExportTests.GoOnlySurface.verified.json |
Updates Go API signatures, numeric types, and formatted declarations. |
Review effort: Balanced
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🔵 Needs a closer look
Unresolved critical defects can break generated Go SDKs and starter projects, produce invalid API exports, corrupt 64-bit results, and allow code injection through unsanitized metadata.
8 open issues
JSON decoding loses precision for 64-bit integer results Generated option names can collide and break compilation Stripping With can make the only option constructor unexported Unsanitized parameter names can inject code through comments Go starter still uses option structs that no longer compile Exported option interfaces are missing their bodies Empty generated types cause an out-of-range slice Declaration scanner drops synthesized application interfaces
Review effort: Balanced
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical defects can convert round-tripped JSON numbers into strings and cause MissingMethodException with older CLIs during SDK generation and API export.
4 open issues
8 resolved since last review
JSON decoding loses precision for 64-bit integer results Generated option names can collide and break compilation Stripping With can make the only option constructor unexported Unsanitized parameter names can inject code through comments Go starter still uses option structs that no longer compile Exported option interfaces are missing their bodies Empty generated types cause an out-of-range slice Declaration scanner drops synthesized application interfaces
Review effort: Balanced
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🔵 Needs a closer look
Human review is needed because generated option names can collide with runtime exports and break SDK compilation, while numeric-union guards can reject forwarded JSON numbers.
No open issues 🎉
4 resolved since last review
Review effort: Balanced
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
This comment has been minimized.
This comment has been minimized.
Carry obsolete metadata through ATS, omit obsolete Go source and API declarations, and retain obsolete types required by active wire signatures. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Probe additive ATS metadata across CLI version skew, preserve untyped JSON numbers, align obsolete dependency traversal, and declare gofmt test prerequisites. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Migrate polyglot validation AppHosts to semantic int and int64 pointer helpers after generated numeric types stopped defaulting to float64. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep TimeSpan and deliberate double fields on Float64Ptr while using Int64Ptr only for CLR long values. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace obsolete generated APIs and wrap direct DTO options so every checked-in Go validation AppHost builds against the new SDK surface. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Dereference optional handle interfaces before wire serialization and reject trailing JSON values while preserving UseNumber. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Execute generated primitive, handle, DTO, ordering, and CreateBuilder options, and declare gofmt prerequisites for RPC export tests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Run gofmt with -s for in-memory generated output and require simplified formatting in source checks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
a7b63b0 to
5550a2e
Compare
This comment has been minimized.
This comment has been minimized.
Reserve embedded runtime identifiers before option naming and accept validated json.Number values in numeric union guards. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tests selector18 / 101 PR test projects · 7 PR jobs, from 70 changed files. Selected PR test projects (18 / 101)
Selected PR jobs (7)
How these were chosen — grouped by what changed
🔧 🔧 🔧 📦 affected project 📦 affected project 📄 🔧 🔧 🔧 🔧 🔧 🔧 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 Job reasons
Selection computed for commit |
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed to evaluate private runtime-name collisions that can break generated SDK compilation and numeric-union regressions that reject previously accepted values.
No open issues 🎉
2 resolved since last review
Review effort: Balanced
|
Pull request created: #2103
|
|
📝 Documentation has been drafted in microsoft/aspire.dev#2103 targeting Updated Go SDK docs for the new option-value pattern ( Note This draft PR needs human review before merging. |
## Description Consolidate the Go AppHost release backports into one PR against `release/17.0`, so shipping the complete Go changes requires one merge rather than three remaining dependent backport merges. David Pine's [November 11 release-order message](https://teams.microsoft.com/l/message/19:86b689da3ce444f8952d0b79157f7562@thread.tacv2/1794418391504?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=f2e0b0b6-f130-46fa-8ec6-2ef4a7168ed2&parentMessageId=1794418391504&teamName=Aspire&channelName=Tactics%20And%20Shiproom&createdTime=1794418391504) opens with "These backports, in this order to get Go AppHost release ready:" and lists #22123, #22057, #22064, and #22121 in that order. The existing backport descriptions specify the same sequence. At preparation time, `release/17.0` points to `9a97ab889bfb731de74ead0280be279ffdd000bf`, the already-merged #22123. This branch first reverts that commit, then reapplies the four original source commits with `git cherry-pick -x` in Pine's order: 1. #21827 / #22123: `e7ff435302acb88f9cfe7c9a61e3633e0f553f08` - harden the Go SDK runtime and complete typed API export metadata. 2. #21969 / #22057: `031536bc9eea22ee9ce2cc1d31bfd30d0c14cfd2` - propagate child resource errors through Build. 3. #21976 / #22064: `cd9e0e8d159d20f3cf7e64eda2415dcc3d40c168` - make generated Go SDK APIs idiomatic. 4. #21874 / #22121: `209d9226e0463b638a5d68a034505e874cae9091` - add the React frontend to the Go starter. The revert exists only on this consolidation branch; the shared release branch was not changed. All four source patches are unchanged (verified with matching patch IDs), with their original source references retained in commit messages. Earlier release prerequisites remain untouched. This PR supersedes #22057, #22064, and #22121, which have been closed with comments linking here. Existing review discussions remain available on those PRs. ### User-facing usage The starter provides a Go API, React frontend, and optional Redis: ```console aspire new aspire-go-starter --non-interactive --use-redis-cache false ``` Use `--use-redis-cache true` to include Redis. Generated projects contain `apphost.go`, `api/`, and `frontend/`. ### Breaking changes The #21976 source change updates generated Go SDK signatures and names. Existing Go AppHosts need to regenerate their SDK and update affected calls. Shared ATS metadata changes are also included. ### Screenshots / Recordings > **This PR includes UI changes.** Please add screenshots or screen recordings so reviewers can evaluate the visual changes without running locally. > > - For before/after comparisons, place them side-by-side or label them clearly. > - For interactive changes (animations, transitions, new flows), prefer a short screen recording (GIF or video). > - If you cannot capture visuals now, note what scenario to test and mark this section as TODO. <!-- Add screenshots/recordings here --> TODO: Visual evidence was not captured. Run the generated Go starter and inspect its React frontend, weather data through the Vite proxy, and optional Redis scenario. ### Security considerations These are unchanged source backports, not new security fixes. They include Go transport/callback/cancellation handling and starter process, proxy, and deployment behavior. Existing review comments on #22057 still need disposition; consolidation does not resolve or invalidate those comments. No new threat-model or security-review result is claimed here. Fixes # (issue) ## 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 - [ ] 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? - [x] Yes - If yes, have you done a threat model and had a security review? - [ ] Yes - [ ] No - [ ] No ## Customer Impact Go AppHost users receive the compatible generated SDK, child-resource error propagation, runtime hardening, and a complete Go/React starter together, without having to assemble dependent backports. ## Testing Validation was performed on the consolidated release-based head `065867bf777dd1e755e2718e8ac979a83fd37613`, not inherited from the source PRs. Test processes used the repo-local `artifacts\tools\go\bin` on PATH (`go version go1.27.4 windows/amd64`). - `.\restore.cmd` - passed; pre-existing NuGet vulnerability warnings were reported. - `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, **137 tests, 0 skipped**, including Go build/vet/runtime and gofmt-dependent tests. An intermediate rerun found generated frontend `node_modules` copied into the scaffold test fixture; removing only generated `node_modules`/`dist` artifacts restored the clean run without source changes. - `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-method "*.GoStarterTemplate*" --filter-method "*.GoStarterHonorsRedisChoice*" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` - passed, **10 tests**. - `dotnet test --project tests\Aspire.Hosting.Go.Tests\Aspire.Hosting.Go.Tests.csproj --no-launch-profile -- --filter-method "*.WithModTidyIsIdempotent" --filter-method "*.WithModTidyCreatesChildResource" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` - passed, **2 tests**. - `dotnet test --project tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj --no-launch-profile -- --filter-class "*.CancellationTokenRegistryTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` - passed, **14 tests**. An earlier attempted filter named `RemoteCancellationRegistryTests` selected zero tests; the corrected run above is the validation result. - `dotnet build tests\Aspire.Cli.EndToEnd.Tests\Aspire.Cli.EndToEnd.Tests.csproj --no-restore` - passed, **0 warnings/errors**. E2E execution was not run on this Windows host. - `npm ci` followed by `npm run build` in `src\Aspire.Cli\Templating\Templates\go-starter\frontend` - passed; TypeScript and Vite production build succeeded. Generated build artifacts were removed afterward. - `dotnet run --project tools\SelectTests -- --from origin/release/17.0 --to HEAD --explain` - passed; **0 unattributed changed files**. `.gitattributes` selects all PR test projects/jobs, including starter validation and polyglot. - `dotnet test --project tests\Infrastructure.Tests\Infrastructure.Tests.csproj --no-launch-profile -- --filter-namespace "Infrastructure.Tests.TestTriggerMap" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` - **364 passed, 22 failed**. Failures are Windows test-harness limitations: Bash subprocesses cannot resolve backslash-delimited Windows script paths, and five git-fixture cleanup cases throw `UnauthorizedAccessException` deleting git objects. This suite is not claimed green; Linux/CI validation is still required. No test or script source was changed. - `git diff --check origin/release/17.0...HEAD` - passed. Starter runtime, Docker deployment, screenshots, full polyglot compatibility suites, and GitHub CI execution were not validated locally. ## Risk Medium. The source changes include shared ATS metadata, breaking generated Go SDK changes, transport/error handling, and starter/frontend deployment behavior. Consolidation preserves the source patches but does not replace review or CI validation. ## Regression? Unknown: the source material does not identify a regressed release. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>


Description
Generated Go AppHosts currently require manual cleanup before standard Go tooling is happy, project every ATS numeric value as
float64, and expose pointer-heavy optional parameter structs. This change makes the generated SDK idiomatic and reviewable as normal Go code..gofile throughgofmtwith deterministic UTF-8 input/output and LF line endings.int,int64,float32,float64, signed, and unsigned Go types while preserving JSON-number wire behavior.XxxOptioninterfaces. Value-shaped options implementapplydirectly; pointer and interface values use small wrappers because Go cannot attach methods to those types.CreateBuilder, while retaining*XxxOptionsas compatible options for existing generated callers.[Obsolete]metadata through ATS and removes obsolete Go methods, properties, DTO members, enum values, exported values, and unreferenced types. Obsolete types required by active wire signatures remain generated.User-facing usage
Endpoint and builder configuration no longer require pointer helpers or struct literals:
The generated option shape is direct and allocation-free for value types:
Validation:
The Go suite includes generated build/test,
go vet, and gofmt validation.Aspire.Cli.EndToEnd.Testsalso builds with 0 warnings and 0 errors.Breaking changes
This intentionally changes the generated Go SDK API:
options ...*XxxOptionsbecomesoptions ...XxxOption.HttpEndpointPort(8080); existing*XxxOptionsvalues remain accepted for source compatibility.CreateBuilder(options ...*CreateBuilderOptions)becomesCreateBuilder(options ...CreateBuilderOption);*CreateBuilderOptionsremains accepted.float64/*float64now use semantic Go types such asint/*int.Fixes # (issue)
Checklist
<remarks />and<code />elements on your triple slash comments?