Merge master (pull 155) into async-scratch-cache

Conflicts: the DI paragraphs in README.md and the AspNetCore README keep the
lifetimes text from master; the pull-request workflow keeps master's note that
pull requests no longer publish and this branch's allowlist and scaling jobs.

Author: Astn

.github/workflows/build_publish_master.yml

@@ -5,6 +5,14 @@ on:
       - "**/*.md"
     branches: [ master ]
 
+# Publishing uses nuget.org Trusted Publishing: the job requests an OIDC token from GitHub, NuGet/login exchanges
+# it for an API key that lives one hour, and the push uses that key. No long-lived NuGet secret is stored here.
+# The nuget.org policy is bound to this repository and to this file's name (build_publish_master.yml); renaming
+# the file or moving the push to another workflow needs a new policy on nuget.org.
+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   build:
 
@@ -24,13 +32,22 @@ jobs:
         run: dotnet restore AustinHarris.JsonRpc.sln
       # Building the solution packs every package project (GeneratePackageOnBuild); `dotnet pack` on the
       # solution would trip NU5026 with GeneratePackageOnBuild, so the packages come from the build.
+      # ContinuousIntegrationBuild makes the build deterministic and lets Source Link map the symbols package
+      # (.snupkg, pushed alongside each .nupkg) back to this commit on GitHub.
       - name: Build
-        run: dotnet build AustinHarris.JsonRpc.sln --configuration Release --no-restore
+        run: dotnet build AustinHarris.JsonRpc.sln --configuration Release --no-restore -p:ContinuousIntegrationBuild=true
       - name: Test
         run: dotnet test AustinHarris.JsonRpcTestN --configuration Release --no-build
+      # The key is requested after the tests so it is fresh for the push (it expires after one hour). `user` is the
+      # nuget.org profile that owns the packages and the trusted publishing policy.
+      - name: NuGet login (OIDC to a temporary API key)
+        uses: NuGet/login@v1
+        id: nuget-login
+        with:
+          user: AustinHarris
       # Publish all four packages: the core and the three companions (Json.NET, System.Text.Json, ASP.NET Core).
       - name: publish nuget version change
         run: |
           for project in Json-Rpc AustinHarris.JsonRpc.Newtonsoft AustinHarris.JsonRpc.SystemTextJson AustinHarris.JsonRpc.AspNetCore; do
-            dotnet nuget push "$project/bin/Release/"*.nupkg --skip-duplicate --source "https://api.nuget.org/v3/index.json" --api-key ${{ secrets.NugetKey }} # API key for the NuGet feed
+            dotnet nuget push "$project/bin/Release/"*.nupkg --skip-duplicate --source "https://api.nuget.org/v3/index.json" --api-key "${{ steps.nuget-login.outputs.NUGET_API_KEY }}"
           done

.github/workflows/build_pull_request.yml

@@ -29,19 +29,11 @@ jobs:
       # Building the solution packs every package project (GeneratePackageOnBuild); `dotnet pack` on the
       # solution would trip NU5026 with GeneratePackageOnBuild, so the packages come from the build.
       - name: Build
-        run: dotnet build AustinHarris.JsonRpc.sln --configuration Release --no-restore --version-suffix ci-${{ github.run_id }}-${{ github.run_number }}
+        run: dotnet build AustinHarris.JsonRpc.sln --configuration Release --no-restore
       - name: Test
         run: dotnet test AustinHarris.JsonRpcTestN --configuration Release --no-build
-      # Publish all four pre-release packages: the core and the three companions (Json.NET, System.Text.Json, ASP.NET Core).
-      # Non-fatal: the build and tests are the pull-request verdict; a rejected key (403) or a fork's missing secret
-      # shows as a warning here and fails loudly in the master workflow instead.
-      - name: publish nuget version change
-        if: ${{ matrix.os == 'ubuntu-latest' }}
-        continue-on-error: true
-        run: |
-          for project in Json-Rpc AustinHarris.JsonRpc.Newtonsoft AustinHarris.JsonRpc.SystemTextJson AustinHarris.JsonRpc.AspNetCore; do
-            dotnet nuget push "$project/bin/Release/"*.nupkg --skip-duplicate --source "https://api.nuget.org/v3/index.json" --api-key ${{ secrets.NugetKey }} # API key for the NuGet feed
-          done
+      # Pull requests do not publish. Packages go out from the master workflow through Trusted Publishing, whose
+      # nuget.org policy is bound to build_publish_master.yml; nothing else can push.
 
   # Every lock and Interlocked on the request-path files must be listed with a reason (a process-wide lock on the
   # per-document path once capped ProcessAsync at 4 M RPC/s on every core count). A review aid, not the measurement.

AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj

@@ -4,26 +4,34 @@
         <Company>Austin Harris</Company>
         <Authors>Austin Harris</Authors>
         <Product>Json-Rpc.Net ASP.NET Core host</Product>
-        <Description>ASP.NET Core / Kestrel hosting for JSON-RPC.Net: MapJsonRpc endpoint (PipeReader in, BodyWriter out, no strings), a raw Kestrel ConnectionHandler for JSON-RPC over TCP, and DI registration of services.</Description>
+        <Description>ASP.NET Core hosting for AustinHarris.JsonRpc. Adds HTTP endpoints and raw Kestrel connections over TCP, Unix sockets and named pipes, with dependency injection.</Description>
         <VersionPrefix>2.0.0</VersionPrefix>
-        <PackageReleaseNotes>https://github.com/Astn/JSON-RPC.NET/blob/master/CHANGELOG.md</PackageReleaseNotes>
-        <VersionSuffix>$(VersionSuffix)</VersionSuffix>
+        <VersionSuffix>preview.1</VersionSuffix>
+        <PackageReleaseNotes>2.0.0-preview.1, released with the core package. What is new: https://astn.github.io/JSON-RPC.NET/changelog.html. Upgrading from 1.x: https://astn.github.io/JSON-RPC.NET/upgrading.html</PackageReleaseNotes>
         <Copyright>Austin Harris</Copyright>
-        <PackageProjectUrl>https://github.com/Astn/JSON-RPC.NET</PackageProjectUrl>
+        <PackageProjectUrl>https://astn.github.io/JSON-RPC.NET/aspnetcore.html</PackageProjectUrl>
         <RepositoryUrl>https://github.com/Astn/JSON-RPC.NET</RepositoryUrl>
         <RepositoryType>git</RepositoryType>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
         <PackageReadmeFile>README.md</PackageReadmeFile>
-        <PackageTags>json-rpc;jsonrpc;json;rpc;server;aspnetcore;kestrel;pipelines</PackageTags>
+        <PackageTags>json-rpc;jsonrpc;json;rpc;server;aspnetcore;asp.net-core;kestrel;pipelines;tcp;net8.0;net10.0</PackageTags>
         <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
         <LangVersion>latest</LangVersion>
         <Nullable>disable</Nullable>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <IncludeSymbols>true</IncludeSymbols>
+        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+        <PublishRepositoryUrl>true</PublishRepositoryUrl>
+        <EmbedUntrackedSources>true</EmbedUntrackedSources>
+        <PackageIcon>icon.png</PackageIcon>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <RootNamespace>AustinHarris.JsonRpc.AspNetCore</RootNamespace>
     </PropertyGroup>
 
     <ItemGroup>
         <None Include="README.md" Pack="true" PackagePath="\" />
+        <None Include="..\icon.png" Pack="true" PackagePath="\" />
     </ItemGroup>
 
     <ItemGroup>

AustinHarris.JsonRpc.AspNetCore/JsonRpcConnectionHandler.Async.cs

@@ -2,6 +2,8 @@
 using System.Threading.Tasks;
 using AustinHarris.JsonRpc.Serialization;
 using Microsoft.AspNetCore.Connections;
+using Microsoft.AspNetCore.Http.Features;
+using Microsoft.Extensions.DependencyInjection;
 
 namespace AustinHarris.JsonRpc.AspNetCore
 {
@@ -35,26 +37,42 @@ private async Task RunAsynchronousMethodsAsync(ConnectionContext connection)
                                 return;
                             }
                             reply.Clear();
-                            var pending = JsonRpcProcessor.ProcessAsync(session, document, reply, connection, _options.Serializer, token);
-                            if (!pending.IsCompleted && wrote)
+                            // The document's service scope, when a scoped or transient service is bound: published for
+                            // the duration of the document and disposed asynchronously after its last response is
+                            // written, which is after the running operation has been awaited on every path below.
+                            var scope = _scopes == null ? default : _scopes.CreateAsyncScope();
+                            if (_scopes != null) connection.Features.Set<IServiceProvidersFeature>(new ServiceProvidersFeature { RequestServices = scope.ServiceProvider });
+                            try
                             {
-                                bool closed = false;
-                                try
+                                var pending = JsonRpcProcessor.ProcessAsync(session, document, reply, connection, _options.Serializer, token);
+                                if (!pending.IsCompleted && wrote)
                                 {
-                                    var flush = await output.FlushAsync(token).ConfigureAwait(false);
-                                    closed = flush.IsCompleted || flush.IsCanceled;
-                                    wrote = false;
+                                    bool closed = false;
+                                    try
+                                    {
+                                        var flush = await output.FlushAsync(token).ConfigureAwait(false);
+                                        closed = flush.IsCompleted || flush.IsCanceled;
+                                        wrote = false;
+                                    }
+                                    finally
+                                    {
+                                        // Even a failed flush cannot release the input or reply while invocation runs.
+                                        await pending.ConfigureAwait(false);
+                                    }
+                                    if (closed) return;
                                 }
-                                finally
+                                else await pending.ConfigureAwait(false);
+                                token.ThrowIfCancellationRequested();
+                                if (reply.WrittenCount != 0) { reply.CopyTo(output); wrote = true; }
+                            }
+                            finally
+                            {
+                                if (_scopes != null)
                                 {
-                                    // Even a failed flush cannot release the input or reply while invocation runs.
-                                    await pending.ConfigureAwait(false);
+                                    connection.Features.Set<IServiceProvidersFeature>(null);
+                                    await scope.DisposeAsync().ConfigureAwait(false);
                                 }
-                                if (closed) return;
                             }
-                            else await pending.ConfigureAwait(false);
-                            token.ThrowIfCancellationRequested();
-                            if (reply.WrittenCount != 0) { reply.CopyTo(output); wrote = true; }
                         }
                         if (wrote)
                         {

AustinHarris.JsonRpc.AspNetCore/JsonRpcConnectionHandler.cs

@@ -1,8 +1,11 @@
 using System;
 using System.Buffers;
+using System.Collections.Generic;
 using System.Threading.Tasks;
 using AustinHarris.JsonRpc.Serialization;
 using Microsoft.AspNetCore.Connections;
+using Microsoft.AspNetCore.Http.Features;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
 
 namespace AustinHarris.JsonRpc.AspNetCore
@@ -12,14 +15,55 @@ namespace AustinHarris.JsonRpc.AspNetCore
     /// back (optionally whitespace / newline separated) and receive responses in order. Wire it up with
     /// <c>kestrel.ListenLocalhost(port, l => l.UseConnectionHandler&lt;JsonRpcConnectionHandler&gt;())</c>.
     /// The connection's <see cref="ConnectionContext"/> is the RPC context for every call.
+    /// When a scoped or transient service is bound to the handler's session, each document runs inside one
+    /// host-owned service scope, published on the connection as <see cref="IServiceProvidersFeature"/> and disposed
+    /// once the document's response is written; the scope never spans documents.
     /// </summary>
     public partial class JsonRpcConnectionHandler : ConnectionHandler
     {
         private readonly JsonRpcOptions _options;
+        /// <summary>Set only when a scoped or transient service is bound to this handler's session: the cost of a scope per document is opt-in.</summary>
+        private readonly IServiceScopeFactory _scopes;
 
-        public JsonRpcConnectionHandler(IOptions<JsonRpcOptions> options)
+        public JsonRpcConnectionHandler(IOptions<JsonRpcOptions> options, IServiceProvider services = null)
         {
             _options = options?.Value ?? new JsonRpcOptions();
+            _scopes = NeedsDocumentScope(services) ? services.GetService<IServiceScopeFactory>() : null;
+        }
+
+        private bool NeedsDocumentScope(IServiceProvider services)
+        {
+            var registrations = services?.GetService<IEnumerable<JsonRpcServiceCollectionExtensions.JsonRpcServiceRegistration>>();
+            if (registrations == null) return false;
+            string session = _options.SessionId ?? Handler.DefaultSessionId();
+            foreach (var r in registrations)
+            {
+                if (r.Lifetime == ServiceLifetime.Singleton) continue;
+                if ((r.SessionId ?? _options.SessionId ?? Handler.DefaultSessionId()) == session) return true;
+            }
+            return false;
+        }
+
+        /// <summary>
+        /// One scope per document: created from <see cref="IServiceScopeFactory"/>, handed to the methods through the
+        /// connection's <see cref="IServiceProvidersFeature"/> (what the default <see cref="JsonRpcOptions.ServiceProviderSelector"/>
+        /// reads), removed and disposed once the whole document, batch included, has been answered. Every call of a
+        /// batch shares it; a transient service is still created per call.
+        /// </summary>
+        private void ProcessInScope(string session, in ReadOnlySequence<byte> document, IBufferWriter<byte> output, ConnectionContext connection)
+        {
+            using (var scope = _scopes.CreateScope())
+            {
+                connection.Features.Set<IServiceProvidersFeature>(new ServiceProvidersFeature { RequestServices = scope.ServiceProvider });
+                try
+                {
+                    JsonRpcProcessor.Process(session, in document, output, connection, _options.Serializer);
+                }
+                finally
+                {
+                    connection.Features.Set<IServiceProvidersFeature>(null);
+                }
+            }
         }
 
         /// <summary>Processes a connection using the hosting mode selected in options.</summary>
@@ -50,7 +94,8 @@ private async Task RunSynchronousMethodsAsync(ConnectionContext connection)
                             connection.Abort(new ConnectionAbortedException("JSON-RPC document exceeds MaxRequestBytes."));
                             return;
                         }
-                        JsonRpcProcessor.Process(session, in document, output, connection, _options.Serializer);
+                        if (_scopes == null) JsonRpcProcessor.Process(session, in document, output, connection, _options.Serializer);
+                        else ProcessInScope(session, in document, output, connection);
                         wrote = true;
                     }
                 }

AustinHarris.JsonRpc.AspNetCore/JsonRpcOptions.cs

@@ -1,6 +1,8 @@
 using System;
 using AustinHarris.JsonRpc.Serialization;
+using Microsoft.AspNetCore.Connections;
 using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Http.Features;
 
 namespace AustinHarris.JsonRpc.AspNetCore
 {
@@ -28,6 +30,26 @@ public class JsonRpcOptions
         /// </summary>
         public Func<HttpContext, object> ContextFactory { get; set; }
 
+        /// <summary>
+        /// Finds the <see cref="IServiceProvider"/> that scoped and transient services (see
+        /// <c>AddJsonRpcService&lt;T&gt;(ServiceLifetime)</c>) are resolved from, given the RPC context of the request
+        /// (what <see cref="JsonRpcContext.Current"/> returns). Without one, the host handles an <see cref="HttpContext"/>
+        /// (its <c>RequestServices</c>) and a raw <see cref="ConnectionContext"/> (the scope the connection handler opens
+        /// per document, published as <see cref="IServiceProvidersFeature"/>). Required when <see cref="ContextFactory"/>
+        /// produces anything else and a non-singleton service is registered: the host refuses to start, and
+        /// <c>MapJsonRpc(pattern, options)</c> refuses to map, otherwise. A selector that returns null falls through to
+        /// the built-in one; when no provider is found the call fails with <c>-32603</c>. The root provider is never used.
+        /// </summary>
+        public Func<object, IServiceProvider> ServiceProviderSelector { get; set; }
+
+        /// <summary>The built-in selection: the HTTP request's services, or the per-document scope of a raw connection.</summary>
+        internal static IServiceProvider DefaultServiceProviderSelector(object context)
+        {
+            if (context is HttpContext http) return http.RequestServices;
+            if (context is ConnectionContext connection) return connection.Features.Get<IServiceProvidersFeature>()?.RequestServices;
+            return null;
+        }
+
         /// <summary>Largest request body accepted, in bytes. Larger bodies get 413. Default 4 MB.</summary>
         public long MaxRequestBytes { get; set; } = 4 * 1024 * 1024;