From 9d86ab2b04a83b7550bad92f3bb5f603543609de Mon Sep 17 00:00:00 2001 From: Blind-Striker Date: Sat, 24 Oct 2026 00:56:21 +0300 Subject: [PATCH 1/2] release: mark 3.0.0 as the released version in the changelog and docs --- CHANGELOG.md | 4 ++-- docs/architecture/client-runtime.md | 4 ++-- docs/architecture/extensions-and-composition.md | 6 +++--- docs/architecture/platform-and-packaging.md | 8 ++++---- docs/engineering/maintenance-playbook.md | 4 ++-- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b6e115..ef704f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ # Changelog -## [Unreleased] +## [v3.0.0](https://github.com/localstack-dotnet/localstack-dotnet-client/releases/tag/v3.0.0) -Planned as **3.0.0** for both packages; not yet published. +> Major release of **both packages**: `LocalStack.Client` 3.0.0 and `LocalStack.Client.Extensions` 3.0.0. ### Breaking changes diff --git a/docs/architecture/client-runtime.md b/docs/architecture/client-runtime.md index b80a42b..524cee8 100644 --- a/docs/architecture/client-runtime.md +++ b/docs/architecture/client-runtime.md @@ -1,6 +1,6 @@ # Client runtime and service mapping -Date: 2026-10-23 +Date: 2026-10-24 The core package creates AWS SDK service clients configured for LocalStack. The [glossary](../../GLOSSARY.md) distinguishes an AWS service, an SDK client, and a configured LocalStack endpoint. @@ -20,4 +20,4 @@ For the modern `Type` APIs and default helper, the [slim generator](../../src/Lo Registry misses and unusual shapes use the previous reflection code only while [`ReflectionFallback.IsSupported`](../../src/LocalStack.Client/Utils/ReflectionFallback.cs) is true. Its feature guard removes that fallback under trimming/Native AOT; the [platform boundary](platform-and-packaging.md#native-aot-and-trimming) lists miss behavior and compiler/type limits. The `netstandard2.0`/`net472` assets keep their previous reflection paths. -[`SessionStandalone`](../../src/LocalStack.Client/SessionStandalone.cs) creates this session without dependency injection. The optional Extensions package owns the application-level mode switch in [Extensions and composition](extensions-and-composition.md). See [platform and packaging](platform-and-packaging.md#native-aot-and-trimming) for the unreleased 3.0.0 Native AOT qualification lane and compiler-asset packaging. +[`SessionStandalone`](../../src/LocalStack.Client/SessionStandalone.cs) creates this session without dependency injection. The optional Extensions package owns the application-level mode switch in [Extensions and composition](extensions-and-composition.md). See [platform and packaging](platform-and-packaging.md#native-aot-and-trimming) for the 3.0.0 Native AOT qualification lane and compiler-asset packaging. diff --git a/docs/architecture/extensions-and-composition.md b/docs/architecture/extensions-and-composition.md index 67e6549..091d38c 100644 --- a/docs/architecture/extensions-and-composition.md +++ b/docs/architecture/extensions-and-composition.md @@ -1,12 +1,12 @@ # Extensions and application composition -Date: 2026-10-23 +Date: 2026-10-24 `LocalStack.Client.Extensions` integrates the core package with .NET configuration and dependency injection. The [client runtime](client-runtime.md) owns endpoint mapping and LocalStack client creation; this document owns application-level composition. -[`AddLocalStack(IConfiguration)`](../../src/LocalStack.Client.Extensions/ServiceCollectionExtensions.cs) binds the `LocalStack` section to `LocalStackOptions`, `SessionOptions`, and `ConfigOptions`. The unreleased implementation uses [fixed-schema typed mutation](../../src/LocalStack.Client.Extensions/LocalStackOptionsBinder.cs), not general reflective configuration binding. Private setters and defaults are retained. Binding stays lazy inside the existing three `Configure` registrations, preserving conversion behavior and the framework's configure/post-configure, validation, and caching pipeline. The aggregate's nested session/configuration objects and the separately registered options remain independent instances. +[`AddLocalStack(IConfiguration)`](../../src/LocalStack.Client.Extensions/ServiceCollectionExtensions.cs) binds the `LocalStack` section to `LocalStackOptions`, `SessionOptions`, and `ConfigOptions`. The implementation uses [fixed-schema typed mutation](../../src/LocalStack.Client.Extensions/LocalStackOptionsBinder.cs), not general reflective configuration binding. Private setters and defaults are retained. Binding stays lazy inside the existing three `Configure` registrations, preserving conversion behavior and the framework's configure/post-configure, validation, and caching pipeline. The aggregate's nested session/configuration objects and the separately registered options remain independent instances. -It registers `IConfig` as transient and `ISessionReflection`, `ISession`, and `IAwsClientFactoryWrapper` as singletons. Registration prepares both client-creation paths; it does not itself enable LocalStack mode. On `net10.0`/`net11.0`, every Add/TryAdd/alias overload uses the generic interface session path in LocalStack mode: with exactly the default `SessionReflection`, AWS SDK v4 static factories create the config/client without runtime reflection or source generation, including in F#/VB. Custom or mocked helpers retain the previous calls and ordering. Core's slim generator serves the `Type` APIs automatically in net10-compatible C# package consumers, including Extensions-only references. The [platform boundary](platform-and-packaging.md#native-aot-and-trimming) owns the unreleased 3.0.0 scope and JIT-only fallback limits. +It registers `IConfig` as transient and `ISessionReflection`, `ISession`, and `IAwsClientFactoryWrapper` as singletons. Registration prepares both client-creation paths; it does not itself enable LocalStack mode. On `net10.0`/`net11.0`, every Add/TryAdd/alias overload uses the generic interface session path in LocalStack mode: with exactly the default `SessionReflection`, AWS SDK v4 static factories create the config/client without runtime reflection or source generation, including in F#/VB. Custom or mocked helpers retain the previous calls and ordering. Core's slim generator serves the `Type` APIs automatically in net10-compatible C# package consumers, including Extensions-only references. The [platform boundary](platform-and-packaging.md#native-aot-and-trimming) owns the 3.0.0 scope and JIT-only fallback limits. `AddAwsService` registers an AWS service interface (singleton by default). When the configured `UseLocalStack` value is `true`, resolution calls `Session.CreateClientByInterface` and uses the LocalStack catalog. When it is `false`—the options default—resolution calls [`AwsClientFactoryWrapper`](../../src/LocalStack.Client.Extensions/AwsClientFactoryWrapper.cs) to create an ordinary AWS SDK client. `AddAWSServiceLocalStack` is an alias for the registration method, **not** an override of the mode switch. `TryAddAwsService` only adds a registration when one is absent. diff --git a/docs/architecture/platform-and-packaging.md b/docs/architecture/platform-and-packaging.md index dfc79a8..1bd63b2 100644 --- a/docs/architecture/platform-and-packaging.md +++ b/docs/architecture/platform-and-packaging.md @@ -1,6 +1,6 @@ # Platform and packaging boundary -Date: 2026-10-23 +Date: 2026-10-24 The source of package versions, target frameworks, and dependencies is the project configuration, not a prose copy of their values: @@ -27,13 +27,13 @@ For Extensions' three target frameworks (`netstandard2.0`, `net10.0`, and `net11 These are this package's consumer minimums, not a copy of the selected [`AWSSDK.Extensions.NETCore.Setup` 4.0.102.4 package ranges](https://www.nuget.org/packages/AWSSDK.Extensions.NETCore.Setup/4.0.102.4). Setup 4.0.102.4 permits older 2.x configuration, logging, and legacy dependency-injection packages, and a `net8.0` dependency-injection package at 8.0.0; those permissive ranges do not lower or define Extensions' own contract. Central versions in [Directory.Packages.props](../../Directory.Packages.props) govern test and sandbox consumers separately. A consumer's resolved graph can select a higher version when another dependency requires it. -The modern-only Options 8.0.2 reference is an unreleased Native AOT fix, not a blanket dependency refresh. It also raises the transitive `Microsoft.Extensions.Primitives` minimum to 8.0.0 on those assets. The `netstandard2.0` dependency floor is unchanged. The centrally managed 10.0.13 versions of other Microsoft.Extensions packages used by tests and sandboxes are not consumer minimums; successful execution with a higher resolved graph does not qualify every declared minimum-version combination. +The modern-only Options 8.0.2 reference is a 3.0.0 Native AOT fix, not a blanket dependency refresh. It also raises the transitive `Microsoft.Extensions.Primitives` minimum to 8.0.0 on those assets. The `netstandard2.0` dependency floor is unchanged. The centrally managed 10.0.13 versions of other Microsoft.Extensions packages used by tests and sandboxes are not consumer minimums; successful execution with a higher resolved graph does not qualify every declared minimum-version combination. -Core targets `netstandard2.0`, `net472`, and the modern targets (`net10.0`, `net11.0`); Extensions targets `netstandard2.0` and the modern targets. Adding a .NET version means adding it to `LocalStackModernTargetFrameworks`; the projects, the packaged generator gate (generated into `buildTransitive/LocalStack.Client.props` at pack time), Cake and the CI Native AOT steps all read it. .NET 8/9 apps select `netstandard2.0` under JIT, without Native AOT; both runtimes reach end of support on 2026-11-10. The .NET 11 RC2 SDK pinned in [global.json](../../global.json) builds `net11.0` until .NET 11 GA on 2026-11-10. Both packages are planned as **3.0.0, unreleased**. Earlier versions are not supported; the [security policy](../../.github/SECURITY.md) owns support windows. Consult the actual package feed before claiming publication. +Core targets `netstandard2.0`, `net472`, and the modern targets (`net10.0`, `net11.0`); Extensions targets `netstandard2.0` and the modern targets. Adding a .NET version means adding it to `LocalStackModernTargetFrameworks`; the projects, the packaged generator gate (generated into `buildTransitive/LocalStack.Client.props` at pack time), Cake and the CI Native AOT steps all read it. .NET 8/9 apps select `netstandard2.0` under JIT, without Native AOT; both runtimes reach end of support on 2026-11-10. The .NET 11 RC2 SDK pinned in [global.json](../../global.json) builds `net11.0` until .NET 11 GA on 2026-11-10. Both packages are versioned **3.0.0**. Earlier versions are not supported; the [security policy](../../.github/SECURITY.md) owns support windows. Consult the actual package feed before claiming publication. ## Native AOT and trimming -The **unreleased 3.0.0 implementation** supports Native AOT and trimming through the existing entry points on `net10.0` and `net11.0`; both package projects set `IsAotCompatible` from `IsLocalStackModernTarget`. LocalStack.NET's own supported client/configuration paths use direct operations without runtime reflection, and Extensions uses fixed-schema options binding. The AWS SDK, DI, and BCL internals have their own status; these statements do not qualify those internals or LocalStack's service coverage. +The **3.0.0 implementation** supports Native AOT and trimming through the existing entry points on `net10.0` and `net11.0`; both package projects set `IsAotCompatible` from `IsLocalStackModernTarget`. LocalStack.NET's own supported client/configuration paths use direct operations without runtime reflection, and Extensions uses fixed-schema options binding. The AWS SDK, DI, and BCL internals have their own status; these statements do not qualify those internals or LocalStack's service coverage. `Session.CreateClientByInterface()`, used by all eight Add/TryAdd/alias overloads in LocalStack mode, uses AWS SDK v4 static factories when the injected helper is exactly the default `SessionReflection`. It creates configuration with `TClient.CreateDefaultClientConfig()`, looks up the endpoint by `ClientConfig.ServiceId`, sets S3 `ForcePathStyle` through a [string-named `UnsafeAccessor`](../../src/LocalStack.Client/Utils/S3ForcePathStyle.cs), and creates the client with `TClient.CreateDefaultServiceClient(...)`. This path needs no generator and also works in F#/VB. Custom or mocked `ISessionReflection` implementations retain the previous helper calls and ordering. diff --git a/docs/engineering/maintenance-playbook.md b/docs/engineering/maintenance-playbook.md index e1e2a53..f87123b 100644 --- a/docs/engineering/maintenance-playbook.md +++ b/docs/engineering/maintenance-playbook.md @@ -1,6 +1,6 @@ # Maintenance playbook -Date: 2026-10-23 +Date: 2026-10-24 This living procedure records the maintainer's preferred maintenance flow adopted on this date. Use it for a routine refresh or select the applicable steps for a focused repair. The order below is present guidance; the representative Git history at the end does not establish a universal historical sequence. @@ -98,4 +98,4 @@ These are sampled accepted commits, not an exhaustive audit or proof of local ed | [05ffff1795f92171b744bcea63fd0b3d2de14848](https://github.com/localstack-dotnet/localstack-dotnet-client/commit/05ffff1795f92171b744bcea63fd0b3d2de14848) | A 3.8.0 message/fixture label accompanies a 3.7.1 image constant: owning inputs matter. | | [f539bf439cfccbff6992643c13d042da085a54b5](https://github.com/localstack-dotnet/localstack-dotnet-client/commit/f539bf439cfccbff6992643c13d042da085a54b5) | Extensions-only repair release preparation with Core's version unchanged. | -The unreleased 3.0.0 implementation includes Native AOT support on `net10.0`/`net11.0`, qualified by the separate native test lane. Consult [platform and packaging](../architecture/platform-and-packaging.md) and its linked projects for the exact boundary, legacy JIT assets, and SDK pin; a target list or successful build does not establish native execution or package publication. +The 3.0.0 implementation includes Native AOT support on `net10.0`/`net11.0`, qualified by the separate native test lane. Consult [platform and packaging](../architecture/platform-and-packaging.md) and its linked projects for the exact boundary, legacy JIT assets, and SDK pin; a target list or successful build does not establish native execution or package publication. From cc140ec43aba6432126a354eb96413f4fb9d60aa Mon Sep 17 00:00:00 2001 From: Blind-Striker Date: Sun, 25 Oct 2026 00:51:23 +0300 Subject: [PATCH 2/2] docs: state the AWS package pins 3.0.0 needs when consumers pin them --- CHANGELOG.md | 3 ++- README.md | 2 +- src/LocalStack.Client.Extensions/README.md | 2 +- src/LocalStack.Client/README.md | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef704f4..d8d7779 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,7 +35,8 @@ ### Dependencies - Core: `AWSSDK.Core` >= 4.0.102.6. -- Extensions: `AWSSDK.Extensions.NETCore.Setup` >= 4.0.102.4. +- Extensions: `AWSSDK.Extensions.NETCore.Setup` >= 4.0.102.4, which itself needs `AWSSDK.Core` >= 4.0.102.11, so Extensions apps resolve at least that Core version. +- Projects that pin `AWSSDK.Core` or `AWSSDK.Extensions.NETCore.Setup` below these versions (for example in `Directory.Packages.props`) get `NU1605` (package downgrade) on restore and must raise the pins. This showed up when upgrading three consumer repositories; no code changes were needed. - Extensions: `Microsoft.Extensions.Configuration.Abstractions`, `Microsoft.Extensions.Configuration.Binder`, `Microsoft.Extensions.Logging.Abstractions`, and `Microsoft.Extensions.Options.ConfigurationExtensions` >= 3.1.32 on all targets. - Extensions: `Microsoft.Extensions.DependencyInjection.Abstractions` >= 3.1.32 on `netstandard2.0` and >= 8.0.0 on `net10.0`/`net11.0`. - Extensions: `Microsoft.Extensions.Options` >= 8.0.2 on `net10.0`/`net11.0` only. diff --git a/README.md b/README.md index a5be0c3..f4a3bbb 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,7 @@ On `net10.0` and `net11.0`, both packages support Native AOT and trimming with n ## Versions and support -3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. If you pin AWS packages yourself, use at least `AWSSDK.Core` 4.0.102.6 with Core and 4.0.102.11 with Extensions, and `AWSSDK.Extensions.NETCore.Setup` 4.0.102.4; lower pins fail restore with `NU1605`. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. ## Known issues diff --git a/src/LocalStack.Client.Extensions/README.md b/src/LocalStack.Client.Extensions/README.md index a5be0c3..f4a3bbb 100644 --- a/src/LocalStack.Client.Extensions/README.md +++ b/src/LocalStack.Client.Extensions/README.md @@ -175,7 +175,7 @@ On `net10.0` and `net11.0`, both packages support Native AOT and trimming with n ## Versions and support -3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. If you pin AWS packages yourself, use at least `AWSSDK.Core` 4.0.102.6 with Core and 4.0.102.11 with Extensions, and `AWSSDK.Extensions.NETCore.Setup` 4.0.102.4; lower pins fail restore with `NU1605`. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. ## Known issues diff --git a/src/LocalStack.Client/README.md b/src/LocalStack.Client/README.md index a5be0c3..f4a3bbb 100644 --- a/src/LocalStack.Client/README.md +++ b/src/LocalStack.Client/README.md @@ -175,7 +175,7 @@ On `net10.0` and `net11.0`, both packages support Native AOT and trimming with n ## Versions and support -3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. If you pin AWS packages yourself, use at least `AWSSDK.Core` 4.0.102.6 with Core and 4.0.102.11 with Extensions, and `AWSSDK.Extensions.NETCore.Setup` 4.0.102.4; lower pins fail restore with `NU1605`. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. ## Known issues