diff --git a/.github/workflows/build_publish_master.yml b/.github/workflows/build_publish_master.yml index 5c6cebf..1a6a319 100644 --- a/.github/workflows/build_publish_master.yml +++ b/.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 diff --git a/.github/workflows/build_pull_request.yml b/.github/workflows/build_pull_request.yml index e22a198..62975b2 100644 --- a/.github/workflows/build_pull_request.yml +++ b/.github/workflows/build_pull_request.yml @@ -29,16 +29,8 @@ 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. diff --git a/AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj b/AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj index 0ca9106..3869014 100644 --- a/AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj +++ b/AustinHarris.JsonRpc.AspNetCore/AustinHarris.JsonRpc.AspNetCore.csproj @@ -4,26 +4,34 @@ Austin Harris Austin Harris Json-Rpc.Net ASP.NET Core host - 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. + ASP.NET Core hosting for AustinHarris.JsonRpc. Adds HTTP endpoints and raw Kestrel connections over TCP, Unix sockets and named pipes, with dependency injection. 2.0.0 - https://github.com/Astn/JSON-RPC.NET/blob/master/CHANGELOG.md - $(VersionSuffix) + preview.1 + 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 Austin Harris - https://github.com/Astn/JSON-RPC.NET + https://astn.github.io/JSON-RPC.NET/aspnetcore.html https://github.com/Astn/JSON-RPC.NET git MIT README.md - json-rpc;jsonrpc;json;rpc;server;aspnetcore;kestrel;pipelines + json-rpc;jsonrpc;json;rpc;server;aspnetcore;asp.net-core;kestrel;pipelines;tcp;net8.0;net10.0 net8.0;net10.0 latest disable + true + $(NoWarn);CS1591 + true + snupkg + true + true + icon.png true AustinHarris.JsonRpc.AspNetCore + diff --git a/AustinHarris.JsonRpc.AspNetCore/README.md b/AustinHarris.JsonRpc.AspNetCore/README.md index 16aba34..97b8f9d 100644 --- a/AustinHarris.JsonRpc.AspNetCore/README.md +++ b/AustinHarris.JsonRpc.AspNetCore/README.md @@ -1,14 +1,17 @@ -# AustinHarris.JsonRpc.AspNetCore +# `AustinHarris.JsonRpc.AspNetCore` -Hosts [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) in ASP.NET Core. The core processes requests as -UTF-8 bytes, so the HTTP endpoint reads the body with `PipeReader` and writes straight into -`Response.BodyWriter`; nothing is turned into a string on the way through. A `ConnectionHandler` does the -same for JSON-RPC over a raw Kestrel connection (TCP, Unix socket, named pipe). +`AustinHarris.JsonRpc.AspNetCore` hosts +[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0 in ASP.NET Core +and registers services through dependency injection. +Choose it for an HTTP endpoint or raw Kestrel connections over TCP, Unix sockets or named pipes. + +The HTTP endpoint reads with `PipeReader` and writes to `Response.BodyWriter` +without converting the document to a string. ## Install -``` -dotnet add package AustinHarris.JsonRpc.AspNetCore +```sh +dotnet add package AustinHarris.JsonRpc.AspNetCore --prerelease ``` Targets `net8.0` and `net10.0`; depends on the `AustinHarris.JsonRpc` core package and the ASP.NET Core shared diff --git a/AustinHarris.JsonRpc.Client.WP7/AustinHarris.JsonRpc.Client.WP7.csproj b/AustinHarris.JsonRpc.Client.WP7/AustinHarris.JsonRpc.Client.WP7.csproj deleted file mode 100644 index fee5804..0000000 --- a/AustinHarris.JsonRpc.Client.WP7/AustinHarris.JsonRpc.Client.WP7.csproj +++ /dev/null @@ -1,109 +0,0 @@ - - - - Debug - AnyCPU - 10.0.20506 - 2.0 - {BFF21670-9DEB-4E36-95F4-96FC9DC740A2} - {C089C8C0-30E0-4E22-80C0-CE093F111A43};{fae04ec0-301f-11d3-bf4b-00c04f79efbc} - Library - Properties - AustinHarris.JsonRpc.Client.WP7 - AustinHarris.JsonRpc.Client.WP7 - v8.0 - - - - - WindowsPhone - false - true - true - SAK - SAK - SAK - SAK - - - - - 4.0 - 11.0 - - - true - full - false - Bin\Debug - DEBUG;TRACE;SILVERLIGHT;WINDOWS_PHONE - true - true - prompt - 4 - - - pdbonly - true - Bin\Release - TRACE;SILVERLIGHT;WINDOWS_PHONE - true - true - prompt - 4 - - - - Bin\x86\Debug - true - full - false - - - - Bin\x86\Release - pdbonly - true - - - - Bin\ARM\Debug - true - full - false - - - - Bin\ARM\Release - pdbonly - true - - - - ..\packages\Newtonsoft.Json.4.5.1\lib\sl4-windowsphone71\Newtonsoft.Json.dll - - - ..\packages\Rx-Main.1.0.11226\lib\SL3-WP\System.Reactive.dll - - - - - JsonRequest.cs - - - JsonResponse.cs - - - - - - - - - \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7/Properties/AssemblyInfo.cs b/AustinHarris.JsonRpc.Client.WP7/Properties/AssemblyInfo.cs deleted file mode 100644 index d3f69ab..0000000 --- a/AustinHarris.JsonRpc.Client.WP7/Properties/AssemblyInfo.cs +++ /dev/null @@ -1,35 +0,0 @@ -using System.Reflection; -using System.Runtime.CompilerServices; -using System.Runtime.InteropServices; - -// General Information about an assembly is controlled through the following -// set of attributes. Change these attribute values to modify the information -// associated with an assembly. -[assembly: AssemblyTitle("AustinHarris.JsonRpc.Client.WP7")] -[assembly: AssemblyDescription("")] -[assembly: AssemblyConfiguration("")] -[assembly: AssemblyCompany("")] -[assembly: AssemblyProduct("AustinHarris.JsonRpc.Client.WP7")] -[assembly: AssemblyCopyright("Copyright © 2012")] -[assembly: AssemblyTrademark("")] -[assembly: AssemblyCulture("")] - -// Setting ComVisible to false makes the types in this assembly not visible -// to COM components. If you need to access a type in this assembly from -// COM, set the ComVisible attribute to true on that type. -[assembly: ComVisible(false)] - -// The following GUID is for the ID of the typelib if this project is exposed to COM -[assembly: Guid("913c7d78-8983-4ebb-9a6b-fe5cb4001abf")] - -// Version information for an assembly consists of the following four values: -// -// Major Version -// Minor Version -// Build Number -// Revision -// -// You can specify all the values or you can default the Revision and Build Numbers -// by using the '*' as shown below: -[assembly: AssemblyVersion("1.0.0.0")] -[assembly: AssemblyFileVersion("1.0.0.0")] diff --git a/AustinHarris.JsonRpc.Client.WP7/client.cs b/AustinHarris.JsonRpc.Client.WP7/client.cs deleted file mode 100644 index 108ea44..0000000 --- a/AustinHarris.JsonRpc.Client.WP7/client.cs +++ /dev/null @@ -1,148 +0,0 @@ -using System; -using System.Collections.Generic; -using System.IO; -using System.Net; -using Newtonsoft.Json.Linq; -using AustinHarris.JsonRpc; -using System.Linq; -using System.Reactive.Linq; -using System.Reactive.Subjects; -using System.Reactive.Concurrency; - -namespace AustinHarris.JsonRpc -{ - public class JsonRpcClient - { - private static object idLock = new object(); - private static int id = 0; - public Uri ServiceEndpoint = null; - - public JsonRpcClient(Uri serviceEndpoint) - { - ServiceEndpoint = serviceEndpoint; - } - - private static Stream CopyAndClose(Stream inputStream) - { - const int readSize = 256; - byte[] buffer = new byte[readSize]; - MemoryStream ms = new MemoryStream(); - - int count = inputStream.Read(buffer, 0, readSize); - while (count > 0) - { - ms.Write(buffer, 0, count); - count = inputStream.Read(buffer, 0, readSize); - } - ms.Position = 0; - inputStream.Close(); - return ms; - } - - public IObservable> Invoke(string method, object arg, IScheduler scheduler) - { - var req = new AustinHarris.JsonRpc.JsonRequest() - { - Method = method, - Params = new object[] { arg } - }; - return Invoke(req, scheduler); - } - - public IObservable> Invoke(string method, object[] args, IScheduler scheduler) - { - var req = new AustinHarris.JsonRpc.JsonRequest() - { - Method = method, - Params = args - }; - return Invoke(req,scheduler); - } - - public IObservable> Invoke(JsonRequest jsonRpc, IScheduler scheduler) - { - var subj = new Subject>(); - - int myId; - lock (idLock) - { - myId = ++id; - } - jsonRpc.Id = myId.ToString(); - - WebRequest req = null; - try - { - req = HttpWebRequest.CreateHttp(new Uri(ServiceEndpoint + "?callid=" + myId.ToString())); - req.Method = "Post"; - req.ContentType = "application/json-rpc"; - } - catch (Exception ex) - { - return Observable.Throw>(ex); - } - - var ar = req.BeginGetRequestStream(new AsyncCallback((iar) => - { - HttpWebRequest request = null; - - try - { - request = (HttpWebRequest)iar.AsyncState; - var json = Newtonsoft.Json.JsonConvert.SerializeObject(jsonRpc); - var reqStream = req.EndGetRequestStream(iar); - using (var stream = new StreamWriter(reqStream)) - { - stream.Write(json); - stream.Flush(); - stream.Close(); - } - } - catch (Exception ex) - { - subj.OnError(ex); - } - - var rar = req.BeginGetResponse(new AsyncCallback((riar) => - { - JsonResponse rjson = null; - string sstream = ""; - try - { - var request1 = (HttpWebRequest)riar.AsyncState; - var resp = (HttpWebResponse)request1.EndGetResponse(riar); - var respStream = resp.GetResponseStream(); - using (var rstream = new StreamReader(CopyAndClose(respStream))) - { - sstream = rstream.ReadToEnd(); - } - - rjson = Newtonsoft.Json.JsonConvert.DeserializeObject>(sstream); - } - catch (Exception ex) - { - subj.OnError(ex); - return; - } - - try - { - if (rjson == null) - { - JObject jo = Newtonsoft.Json.JsonConvert.DeserializeObject(sstream) as JObject; - subj.OnError(new Exception(jo["Error"].ToString())); - return; - } - } - catch (Exception) - { } - - subj.OnNext(rjson); - subj.OnCompleted(); - }), request); - }), req); - - return subj; - } - } -} diff --git a/AustinHarris.JsonRpc.Client.WP7Test/App.xaml b/AustinHarris.JsonRpc.Client.WP7Test/App.xaml deleted file mode 100644 index 0eb20ff..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/App.xaml +++ /dev/null @@ -1,19 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/App.xaml.cs b/AustinHarris.JsonRpc.Client.WP7Test/App.xaml.cs deleted file mode 100644 index cf90a39..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/App.xaml.cs +++ /dev/null @@ -1,142 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Net; -using System.Windows; -using System.Windows.Controls; -using System.Windows.Documents; -using System.Windows.Input; -using System.Windows.Media; -using System.Windows.Media.Animation; -using System.Windows.Navigation; -using System.Windows.Shapes; -using Microsoft.Phone.Controls; -using Microsoft.Phone.Shell; - -namespace AustinHarris.JsonRpc.Client.WP7Test -{ - public partial class App : Application - { - /// - /// Provides easy access to the root frame of the Phone Application. - /// - /// The root frame of the Phone Application. - public PhoneApplicationFrame RootFrame { get; private set; } - - /// - /// Constructor for the Application object. - /// - public App() - { - // Global handler for uncaught exceptions. - UnhandledException += Application_UnhandledException; - - // Standard Silverlight initialization - InitializeComponent(); - - // Phone-specific initialization - InitializePhoneApplication(); - - // Show graphics profiling information while debugging. - if (System.Diagnostics.Debugger.IsAttached) - { - // Display the current frame rate counters. - Application.Current.Host.Settings.EnableFrameRateCounter = true; - - // Show the areas of the app that are being redrawn in each frame. - //Application.Current.Host.Settings.EnableRedrawRegions = true; - - // Enable non-production analysis visualization mode, - // which shows areas of a page that are handed off to GPU with a colored overlay. - //Application.Current.Host.Settings.EnableCacheVisualization = true; - - // Disable the application idle detection by setting the UserIdleDetectionMode property of the - // application's PhoneApplicationService object to Disabled. - // Caution:- Use this under debug mode only. Application that disables user idle detection will continue to run - // and consume battery power when the user is not using the phone. - PhoneApplicationService.Current.UserIdleDetectionMode = IdleDetectionMode.Disabled; - } - - } - - // Code to execute when the application is launching (eg, from Start) - // This code will not execute when the application is reactivated - private void Application_Launching(object sender, LaunchingEventArgs e) - { - } - - // Code to execute when the application is activated (brought to foreground) - // This code will not execute when the application is first launched - private void Application_Activated(object sender, ActivatedEventArgs e) - { - } - - // Code to execute when the application is deactivated (sent to background) - // This code will not execute when the application is closing - private void Application_Deactivated(object sender, DeactivatedEventArgs e) - { - } - - // Code to execute when the application is closing (eg, user hit Back) - // This code will not execute when the application is deactivated - private void Application_Closing(object sender, ClosingEventArgs e) - { - } - - // Code to execute if a navigation fails - private void RootFrame_NavigationFailed(object sender, NavigationFailedEventArgs e) - { - if (System.Diagnostics.Debugger.IsAttached) - { - // A navigation has failed; break into the debugger - System.Diagnostics.Debugger.Break(); - } - } - - // Code to execute on Unhandled Exceptions - private void Application_UnhandledException(object sender, ApplicationUnhandledExceptionEventArgs e) - { - if (System.Diagnostics.Debugger.IsAttached) - { - // An unhandled exception has occurred; break into the debugger - System.Diagnostics.Debugger.Break(); - } - } - - #region Phone application initialization - - // Avoid double-initialization - private bool phoneApplicationInitialized = false; - - // Do not add any additional code to this method - private void InitializePhoneApplication() - { - if (phoneApplicationInitialized) - return; - - // Create the frame but don't set it as RootVisual yet; this allows the splash - // screen to remain active until the application is ready to render. - RootFrame = new PhoneApplicationFrame(); - RootFrame.Navigated += CompleteInitializePhoneApplication; - - // Handle navigation failures - RootFrame.NavigationFailed += RootFrame_NavigationFailed; - - // Ensure we don't initialize again - phoneApplicationInitialized = true; - } - - // Do not add any additional code to this method - private void CompleteInitializePhoneApplication(object sender, NavigationEventArgs e) - { - // Set the root visual to allow the application to render - if (RootVisual != RootFrame) - RootVisual = RootFrame; - - // Remove this handler since it is no longer needed - RootFrame.Navigated -= CompleteInitializePhoneApplication; - } - - #endregion - } -} \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/ApplicationIcon.png b/AustinHarris.JsonRpc.Client.WP7Test/ApplicationIcon.png deleted file mode 100644 index 5859393..0000000 Binary files a/AustinHarris.JsonRpc.Client.WP7Test/ApplicationIcon.png and /dev/null differ diff --git a/AustinHarris.JsonRpc.Client.WP7Test/AustinHarris.JsonRpc.Client.WP7Test.csproj b/AustinHarris.JsonRpc.Client.WP7Test/AustinHarris.JsonRpc.Client.WP7Test.csproj deleted file mode 100644 index 0e22e65..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/AustinHarris.JsonRpc.Client.WP7Test.csproj +++ /dev/null @@ -1,147 +0,0 @@ - - - - Debug - AnyCPU - 10.0.20506 - 2.0 - {0838766E-01BD-4B62-9F0B-2C1FB3B39DBD} - {C089C8C0-30E0-4E22-80C0-CE093F111A43};{fae04ec0-301f-11d3-bf4b-00c04f79efbc} - Library - Properties - AustinHarris.JsonRpc.Client.WP7Test - AustinHarris.JsonRpc.Client.WP7Test - v8.0 - - - - - WindowsPhone - true - - - true - true - AustinHarris.JsonRpc.Client.WP7Test_$(Configuration)_$(Platform).xap - Properties\AppManifest.xml - AustinHarris.JsonRpc.Client.WP7Test.App - true - true - SAK - SAK - SAK - SAK - - - - - 4.0 - 11.0 - - - true - full - false - Bin\Debug - DEBUG;TRACE;SILVERLIGHT;WINDOWS_PHONE - true - true - prompt - 4 - - - pdbonly - true - Bin\Release - TRACE;SILVERLIGHT;WINDOWS_PHONE - true - true - prompt - 4 - - - - Bin\x86\Debug - true - full - false - - - - Bin\x86\Release - pdbonly - true - - - - Bin\ARM\Debug - true - full - false - - - - Bin\ARM\Release - pdbonly - true - - - - ..\packages\Rx-Main.1.0.11226\lib\SL3-WP\System.Reactive.dll - - - - - App.xaml - - - MainPage.xaml - - - - - - Designer - MSBuild:Compile - MSBuild:Compile - Designer - - - Designer - MSBuild:Compile - MSBuild:Compile - Designer - - - - - - Designer - - - - - PreserveNewest - - - PreserveNewest - - - - - - {BFF21670-9DEB-4E36-95F4-96FC9DC740A2} - AustinHarris.JsonRpc.Client.WP7 - - - - - - - \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/Background.png b/AustinHarris.JsonRpc.Client.WP7Test/Background.png deleted file mode 100644 index e46f21d..0000000 Binary files a/AustinHarris.JsonRpc.Client.WP7Test/Background.png and /dev/null differ diff --git a/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml b/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml deleted file mode 100644 index 4b513ff..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml +++ /dev/null @@ -1,45 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml.cs b/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml.cs deleted file mode 100644 index e4488a4..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/MainPage.xaml.cs +++ /dev/null @@ -1,49 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Net; -using System.Windows; -using System.Windows.Controls; -using System.Windows.Documents; -using System.Windows.Input; -using System.Windows.Media; -using System.Windows.Media.Animation; -using System.Windows.Shapes; -using Microsoft.Phone.Controls; -using System.Reactive.Concurrency; - -namespace AustinHarris.JsonRpc.Client.WP7Test -{ - public partial class MainPage : PhoneApplicationPage - { - // Constructor - public MainPage() - { - InitializeComponent(); - } - JsonResponse response; - Exception ex; - bool done; - protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e) - { - base.OnNavigatedTo(e); - JsonRpcClient client = new JsonRpcClient(new Uri("http://localhost:49718/json.rpc")); - var request = client.Invoke("internal.echo", "hi", Scheduler.ThreadPool); - - request.Subscribe( - response => - { - this.response = response; - }, - error => - { - ex = error; - }, - () => - { - done = true; - } - ); - } - } -} \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/Properties/AppManifest.xml b/AustinHarris.JsonRpc.Client.WP7Test/Properties/AppManifest.xml deleted file mode 100644 index 6712a11..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/Properties/AppManifest.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - diff --git a/AustinHarris.JsonRpc.Client.WP7Test/Properties/AssemblyInfo.cs b/AustinHarris.JsonRpc.Client.WP7Test/Properties/AssemblyInfo.cs deleted file mode 100644 index f27f7fa..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/Properties/AssemblyInfo.cs +++ /dev/null @@ -1,35 +0,0 @@ -using System.Reflection; -using System.Runtime.CompilerServices; -using System.Runtime.InteropServices; - -// General Information about an assembly is controlled through the following -// set of attributes. Change these attribute values to modify the information -// associated with an assembly. -[assembly: AssemblyTitle("AustinHarris.JsonRpc.Client.WP7Test")] -[assembly: AssemblyDescription("")] -[assembly: AssemblyConfiguration("")] -[assembly: AssemblyCompany("")] -[assembly: AssemblyProduct("AustinHarris.JsonRpc.Client.WP7Test")] -[assembly: AssemblyCopyright("Copyright © 2012")] -[assembly: AssemblyTrademark("")] -[assembly: AssemblyCulture("")] - -// Setting ComVisible to false makes the types in this assembly not visible -// to COM components. If you need to access a type in this assembly from -// COM, set the ComVisible attribute to true on that type. -[assembly: ComVisible(false)] - -// The following GUID is for the ID of the typelib if this project is exposed to COM -[assembly: Guid("9172e0a2-66d0-48b4-987f-a656d1634bb3")] - -// Version information for an assembly consists of the following four values: -// -// Major Version -// Minor Version -// Build Number -// Revision -// -// You can specify all the values or you can default the Revision and Build Numbers -// by using the '*' as shown below: -[assembly: AssemblyVersion("1.0.0.0")] -[assembly: AssemblyFileVersion("1.0.0.0")] diff --git a/AustinHarris.JsonRpc.Client.WP7Test/Properties/WMAppManifest.xml b/AustinHarris.JsonRpc.Client.WP7Test/Properties/WMAppManifest.xml deleted file mode 100644 index 37010b4..0000000 --- a/AustinHarris.JsonRpc.Client.WP7Test/Properties/WMAppManifest.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - - ApplicationIcon.png - - - - - - - - - - - - - - - - - - - - - - - - - Background.png - 0 - Background.png - AustinHarris.JsonRpc.Client.WP7Test - - - - - false - - - - - - - - - - \ No newline at end of file diff --git a/AustinHarris.JsonRpc.Client.WP7Test/SplashScreenImage.jpg b/AustinHarris.JsonRpc.Client.WP7Test/SplashScreenImage.jpg deleted file mode 100644 index 353b192..0000000 Binary files a/AustinHarris.JsonRpc.Client.WP7Test/SplashScreenImage.jpg and /dev/null differ diff --git a/AustinHarris.JsonRpc.Newtonsoft/AustinHarris.JsonRpc.Newtonsoft.csproj b/AustinHarris.JsonRpc.Newtonsoft/AustinHarris.JsonRpc.Newtonsoft.csproj index 3eacf84..22d3b2a 100644 --- a/AustinHarris.JsonRpc.Newtonsoft/AustinHarris.JsonRpc.Newtonsoft.csproj +++ b/AustinHarris.JsonRpc.Newtonsoft/AustinHarris.JsonRpc.Newtonsoft.csproj @@ -4,26 +4,34 @@ Austin Harris Austin Harris Json-Rpc.Net Json.NET serializer - Json.NET (Newtonsoft.Json) serializer for JSON-RPC.Net. Lenient parsing and full Json.NET conversion semantics; pass JsonSerializerSettings to control it. + Json.NET serializer for AustinHarris.JsonRpc. Uses JsonSerializerSettings for converters, contract resolvers and lenient JSON input. 2.0.0 - https://github.com/Astn/JSON-RPC.NET/blob/master/CHANGELOG.md - $(VersionSuffix) + preview.1 + 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 Austin Harris - https://github.com/Astn/JSON-RPC.NET + https://astn.github.io/JSON-RPC.NET/newtonsoft.html https://github.com/Astn/JSON-RPC.NET git MIT README.md - json-rpc;jsonrpc;json;rpc;server;json.net;newtonsoft + json-rpc;jsonrpc;json;rpc;server;json.net;newtonsoft;serializer;netstandard2.0;netstandard2.1;net8.0;net10.0 netstandard2.0;netstandard2.1;net8.0;net10.0 latest true + true + $(NoWarn);CS1591 + true + snupkg + true + true + icon.png true AustinHarris.JsonRpc.Newtonsoft + diff --git a/AustinHarris.JsonRpc.Newtonsoft/README.md b/AustinHarris.JsonRpc.Newtonsoft/README.md index 07b305b..6e5c0fd 100644 --- a/AustinHarris.JsonRpc.Newtonsoft/README.md +++ b/AustinHarris.JsonRpc.Newtonsoft/README.md @@ -1,14 +1,16 @@ -# AustinHarris.JsonRpc.Newtonsoft +# `AustinHarris.JsonRpc.Newtonsoft` -Json.NET (Newtonsoft.Json) serializer for [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) 2.0. +`AustinHarris.JsonRpc.Newtonsoft` adds Json.NET serialization to +[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0. +Choose it when your models rely on Json.NET converters, contract resolvers or `[JsonProperty]`, +or when clients send non-strict JSON. -The core package (`AustinHarris.JsonRpc`) parses the JSON-RPC envelope itself and ships a built-in serializer for -parameters and results that needs no JSON library. Install this package when you want Json.NET to do the value -conversions: its converters, contract resolvers, `[JsonProperty]` attributes, date/float handling, and its -tolerance for non-strict JSON. +Configure parameter and result conversion with `JsonSerializerSettings`. -``` -dotnet add package AustinHarris.JsonRpc.Newtonsoft +## Install + +```sh +dotnet add package AustinHarris.JsonRpc.Newtonsoft --prerelease ``` Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`; depends on Newtonsoft.Json 13.0.4 and the diff --git a/AustinHarris.JsonRpc.SystemTextJson/AustinHarris.JsonRpc.SystemTextJson.csproj b/AustinHarris.JsonRpc.SystemTextJson/AustinHarris.JsonRpc.SystemTextJson.csproj index 5035c86..2f69a74 100644 --- a/AustinHarris.JsonRpc.SystemTextJson/AustinHarris.JsonRpc.SystemTextJson.csproj +++ b/AustinHarris.JsonRpc.SystemTextJson/AustinHarris.JsonRpc.SystemTextJson.csproj @@ -4,25 +4,33 @@ Austin Harris Austin Harris Json-Rpc.Net System.Text.Json serializer - System.Text.Json serializer for JSON-RPC.Net. Utf8JsonReader/Utf8JsonWriter end to end; pass JsonSerializerOptions to control it. + System.Text.Json serializer for AustinHarris.JsonRpc. Reads UTF-8 parameters and writes results directly to the response buffer, configured with JsonSerializerOptions. 2.0.0 - https://github.com/Astn/JSON-RPC.NET/blob/master/CHANGELOG.md - $(VersionSuffix) + preview.1 + 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 Austin Harris - https://github.com/Astn/JSON-RPC.NET + https://astn.github.io/JSON-RPC.NET/systemtextjson.html https://github.com/Astn/JSON-RPC.NET git MIT README.md - json-rpc;jsonrpc;json;rpc;server;system.text.json + json-rpc;jsonrpc;json;rpc;server;system.text.json;serializer;netstandard2.0;netstandard2.1;net8.0;net10.0 netstandard2.0;netstandard2.1;net8.0;net10.0 latest + true + $(NoWarn);CS1591 + true + snupkg + true + true + icon.png true AustinHarris.JsonRpc.SystemTextJson + diff --git a/AustinHarris.JsonRpc.SystemTextJson/README.md b/AustinHarris.JsonRpc.SystemTextJson/README.md index b0aee69..03d4d52 100644 --- a/AustinHarris.JsonRpc.SystemTextJson/README.md +++ b/AustinHarris.JsonRpc.SystemTextJson/README.md @@ -1,15 +1,17 @@ -# AustinHarris.JsonRpc.SystemTextJson +# `AustinHarris.JsonRpc.SystemTextJson` -System.Text.Json serializer for [JSON-RPC.Net](https://github.com/Astn/JSON-RPC.NET) 2.0. The core parses the -JSON-RPC envelope (method / params / id) itself and asks the serializer only to convert values: request -parameters arrive as the raw UTF-8 bytes of one JSON value and go straight into `JsonSerializer.Deserialize` -(no transcoding, no copies); results are written with a per-thread cached `Utf8JsonWriter` directly into the +`AustinHarris.JsonRpc.SystemTextJson` adds `System.Text.Json` serialization to +[`AustinHarris.JsonRpc`](https://www.nuget.org/packages/AustinHarris.JsonRpc) 2.0. +Choose it when your application already uses `JsonSerializerOptions` and `System.Text.Json` converters. + +Request parameters arrive as the raw UTF-8 bytes of one JSON value and go straight into `JsonSerializer.Deserialize`, +with no transcoding and no copies. Results are written with a per-thread cached `Utf8JsonWriter` directly into the response buffer. ## Install -``` -dotnet add package AustinHarris.JsonRpc.SystemTextJson +```sh +dotnet add package AustinHarris.JsonRpc.SystemTextJson --prerelease ``` Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`; depends on System.Text.Json 10.0.3 and the diff --git a/CHANGELOG.md b/CHANGELOG.md index d229ddb..5f05bef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,13 @@ The four packages (`AustinHarris.JsonRpc`, `AustinHarris.JsonRpc.Newtonsoft`, `AustinHarris.JsonRpc.SystemTextJson`, `AustinHarris.JsonRpc.AspNetCore`) share one version number and are released together. This file is the record -of what changed in each version; the README's [Upgrading from 1.x](README.md#upgrading-from-1x) explains how to -move a 1.x server, and the package pages on NuGet link here. +of what changed in each version; [Upgrading from 1.x](docs/upgrading.md) explains how to move a 1.x server, and +the package pages on NuGet link here. Versions follow [Semantic Versioning](https://semver.org/) for the public API and the documented wire behaviour: a breaking change to either means a new major version. -## 2.0.0 (unreleased) +## 2.0.0 (in preview: `2.0.0-preview.1`) ### Added diff --git a/Json-Rpc/AustinHarris.JsonRpc.csproj b/Json-Rpc/AustinHarris.JsonRpc.csproj index a6b3721..f704c10 100644 --- a/Json-Rpc/AustinHarris.JsonRpc.csproj +++ b/Json-Rpc/AustinHarris.JsonRpc.csproj @@ -4,24 +4,32 @@ Austin Harris Austin Harris Json-Rpc.Net Core - JSON-RPC.Net is a high performance JSON-RPC 2.0 server for .NET Standard 2.0+ and modern .NET. Bytes in, bytes out, no JSON library dependency: the built-in serializer needs nothing, and Json.NET or System.Text.Json plug in through the companion packages. Host it in ASP.NET Core / Kestrel, a console app, sockets, pipes - anything that can hand you UTF-8 or a string. + High-throughput JSON-RPC 2.0 server library for .NET Standard 2.0 through .NET 10: UTF-8 bytes in and out, no JSON library dependency, with Json.NET, System.Text.Json and ASP.NET Core hosting as companion packages. 2.0.0 - $(VersionSuffix) + preview.1 Austin Harris - https://github.com/Astn/JSON-RPC.NET + https://astn.github.io/JSON-RPC.NET/ https://github.com/Astn/JSON-RPC.NET git MIT README.md - json-rpc;jsonrpc;json;rpc;server;netstandard;kestrel;pipelines;system.text.json;json.net;fast - https://github.com/Astn/JSON-RPC.NET/blob/master/CHANGELOG.md + json-rpc;jsonrpc;json;rpc;server;netstandard;netstandard2.0;netstandard2.1;net8.0;net10.0;kestrel;pipelines;system.text.json;json.net;fast + 2.0.0-preview.1: the request pipeline rebuilt around UTF-8 bytes, the JSON serializer pluggable, Task and ValueTask methods supported again, about ten times the throughput of 1.2.3 on the same machine. 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 netstandard2.0;netstandard2.1;net8.0;net10.0 latest + true + $(NoWarn);CS1591 + true + snupkg + true + true + icon.png true - + + diff --git a/Json-Rpc/README.md b/Json-Rpc/README.md new file mode 100644 index 0000000..69b1037 --- /dev/null +++ b/Json-Rpc/README.md @@ -0,0 +1,150 @@ +# `AustinHarris.JsonRpc` + +`AustinHarris.JsonRpc` is a JSON-RPC 2.0 server library for .NET. +Give it a UTF-8 request document and receive the response document: bytes in, bytes out. +It handles parsing, method dispatch, parameter binding, batches and error responses. +You supply the transport. + +The core has no JSON library dependency. +Its built-in serializer works on its own; companion packages add Json.NET, +`System.Text.Json` or ASP.NET Core hosting. + +Targets `netstandard2.0`, `netstandard2.1`, `net8.0` and `net10.0`. +This is a server library, with no client proxies or server-to-client calls. + +## Install + +2.0 is a prerelease. Include `--prerelease` when installing: + +```sh +dotnet add package AustinHarris.JsonRpc --prerelease +``` + +Coming from 1.x? Read [What is new in 2.0](https://astn.github.io/JSON-RPC.NET/changelog.html) and [Upgrading from 1.x](https://astn.github.io/JSON-RPC.NET/upgrading.html) first. + +## Getting started + +### Declare a service + +Create `CalculatorService.cs` with the service below. +Derive from `JsonRpcService` and mark exposed methods with `[JsonRpcMethod]`. +Constructing the service registers its methods in the default session. + +```csharp +using AustinHarris.JsonRpc; + +public class CalculatorService : JsonRpcService +{ + [JsonRpcMethod] // exposed as "add" + private double add(double l, double r) => l + r; + + [JsonRpcMethod("multiply")] // exposed under an explicit name + public int Multiply(int l, int r) => l * r; + + [JsonRpcMethod] + public string StringMe(string x) => x; +} +``` + +Methods can be `private`. Parameters can be positional or named. +Keep the service instance alive; it serves concurrent requests, so its state must be thread-safe. + +### Process requests + +Put this code in `Program.cs` in a console project targeting `net8.0` or `net10.0`. +It calls the service through both string overloads and the byte entry point. +The string overloads transcode into the byte pipeline. + +```csharp +using System; +using System.Buffers; +using System.Text; +using AustinHarris.JsonRpc; + +var service = new CalculatorService(); // binds itself to the default session; keep a reference + +// Strings, asynchronous invocation. +string response = await JsonRpcProcessor.ProcessAsync("{\"jsonrpc\":\"2.0\",\"method\":\"add\",\"params\":[1,2],\"id\":1}"); +// {"jsonrpc":"2.0","result":3.0,"id":1} + +// Strings, synchronous, on the calling thread. Named parameters. +string sync = JsonRpcProcessor.ProcessSync("{\"method\":\"multiply\",\"params\":{\"l\":6,\"r\":7},\"id\":2}"); +// {"jsonrpc":"2.0","result":42,"id":2} + +// Bytes: the native path. The string overloads transcode into it. +byte[] request = Encoding.UTF8.GetBytes("{\"method\":\"add\",\"params\":[2,3],\"id\":3}"); +var output = new ArrayBufferWriter(); +JsonRpcProcessor.Process(Handler.DefaultSessionId(), request.AsSpan(), output); +Console.WriteLine(Encoding.UTF8.GetString(output.WrittenSpan)); // nothing is written for a notification +``` + +The string responses appear in the comments above. The byte call prints: + +```json +{"jsonrpc":"2.0","result":5.0,"id":3} +``` + +A batch returns an array when it contains calls that need responses. +A notification has no `id` and produces no response. +Pass a `byte[]` as `AsSpan()` to select the span overload. + +Use `JsonRpcProcessor.ProcessAsync` for methods returning `Task` or `ValueTask`. +The synchronous entry points do not await those methods. + +## Performance + +These results compare 1.2.3 and 2.0 with the same five requests on the same machine in one session. +The 2.0 runs used the built-in serializer on an AMD Ryzen 7 7800X3D with .NET 10, Release and Server GC. + +![JSON-RPC.Net 1.2.3 and 2.0 throughput through the string and byte entry points](https://raw.githubusercontent.com/Astn/JSON-RPC.NET/master/benchmarks/charts/headline-1x-vs-2.svg) + +| Path | RPC/s | Against 1.2.3 | +| --- | ---: | ---: | +| 1.2.3, `Task Process(string)`, thread pool, best batch size | 3.08 M | | +| 2.0, the same string API and the same loop | 13.3 M | 4.3× | +| 2.0, `Process(bytes)`, 16 dedicated threads | 31.7 M | 10.3× | +| 2.0, `ProcessAsync(bytes)`, 16 awaited workers | 32.1 M | 10.4× | + +These measurements cover the library without a transport. +The asynchronous byte row uses methods that complete inline. +For Kestrel TCP with 256 requests in flight per connection and `EnableAsyncMethods = false`, +the measured range is 14.3 M to 16.5 M RPC/s on loopback, with clients and server on the same machine. + +See the [benchmark tables](https://astn.github.io/JSON-RPC.NET/#benchmarks) for conditions +and the [benchmark explorer](https://astn.github.io/JSON-RPC.NET/benchmarks/charts/explorer.html) for the data. + +## Companion packages + +Install only the integrations your host needs. Use matching package versions. + +- [`AustinHarris.JsonRpc.Newtonsoft`](https://astn.github.io/JSON-RPC.NET/newtonsoft.html): Json.NET converters, contract resolvers, `[JsonProperty]`, `JsonSerializerSettings` and lenient input. +- [`AustinHarris.JsonRpc.SystemTextJson`](https://astn.github.io/JSON-RPC.NET/systemtextjson.html): `System.Text.Json` conversion with `JsonSerializerOptions`, reading and writing UTF-8 values. +- [`AustinHarris.JsonRpc.AspNetCore`](https://astn.github.io/JSON-RPC.NET/aspnetcore.html): HTTP endpoints, raw Kestrel connections over TCP, Unix sockets or named pipes, and dependency injection. + +## Upgrading from 1.x + +Most service methods can stay as they are. Review these changes before switching: + +- Json.NET is now a companion package. Use it for `JsonSerializerSettings` and settings-based + compatibility helpers; `JsonRequest.Params` follows the selected serializer's object model. +- Review string overloads, especially calls with a positional null context. + Name the `context` argument explicitly; serializer-taking overloads have changed. +- Check client-visible behaviour: notifications never return responses, responding batches stay arrays, + and version values, named parameters and conversion failures are validated. +- Unhandled exceptions now return internal errors with exception details hidden by default. + +[Upgrading from 1.x](https://astn.github.io/JSON-RPC.NET/upgrading.html) covers every API and wire change, and +[What is new in 2.0](https://astn.github.io/JSON-RPC.NET/changelog.html) is the full changelog. + +## Documentation + +- [Server guide](https://astn.github.io/JSON-RPC.NET/) +- [Hosting](https://astn.github.io/JSON-RPC.NET/#hosting) +- [Configuration](https://astn.github.io/JSON-RPC.NET/#configuration) +- [Errors and exception handling](https://astn.github.io/JSON-RPC.NET/#errors) +- [Asynchronous methods and cancellation](https://astn.github.io/JSON-RPC.NET/#asynchronous-methods-and-cancellation) +- [Security and host responsibilities](https://astn.github.io/JSON-RPC.NET/#security) +- [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) +- [Source repository](https://github.com/Astn/JSON-RPC.NET) +- [MIT license](https://github.com/Astn/JSON-RPC.NET/blob/master/LICENSE) diff --git a/Json-Rpc/ServiceBinder.cs b/Json-Rpc/ServiceBinder.cs index 62b3b36..f797161 100644 --- a/Json-Rpc/ServiceBinder.cs +++ b/Json-Rpc/ServiceBinder.cs @@ -33,7 +33,7 @@ public static void BindMethod(string name, Delegate implementation, string[] par /// when given (null entries keep the lambda's own name), else by the /// lambda's parameter names, else arg1, arg2... for a delegate whose names are not recoverable. /// (keyed by JSON name) make those parameters optional. The name must be free: - /// re-registering a name is an error, unlike attribute binding; unbind it first with . + /// re-registering a name is an error, unlike attribute binding; unbind it first with . /// Task and ValueTask delegates require ProcessAsync; async void is rejected. /// controls ambient context across awaits. /// diff --git a/README.md b/README.md index da41d8f..8c73a25 100644 --- a/README.md +++ b/README.md @@ -60,9 +60,11 @@ The core uses no reflection emit, so it runs under the WebAssembly interpreter a ## Installation ``` -dotnet add package AustinHarris.JsonRpc +dotnet add package AustinHarris.JsonRpc --prerelease ``` +2.0 is published as `2.0.0-preview.1`; without `--prerelease`, NuGet resolves to the last 1.x release. + Add `AustinHarris.JsonRpc.Newtonsoft` or `AustinHarris.JsonRpc.SystemTextJson` if you want that serializer, and `AustinHarris.JsonRpc.AspNetCore` to host in Kestrel. ## Getting started @@ -616,42 +618,13 @@ Under the previous harness (one pass per batch, workstation GC) the two-million ## Upgrading from 1.x -Most 1.x services run unchanged. Read the first list before you build, and the second before you deploy next to existing clients. - -### Changes that break the build - -- **Serializer.** `JsonRpcProcessor.Process(…, JsonSerializerSettings)` is gone from the core. Use `Config.SetSerializer(new NewtonsoftJsonRpcSerializer(settings))` from the Newtonsoft package, or the helper overloads there that take the settings. -- **Overloads.** The default-session string overloads that take a serializer take it first: `Process(serializer, json, context)` and `ProcessSync(serializer, json, context)`. `ProcessSync(sessionId, json, context, serializer)` makes `context` required, so `ProcessSync(json, null)` still means the default session. `Process` and `ProcessAsync` do not: `Process(json, null)` no longer compiles (it is ambiguous with the `JsonRpcStateAsync` overload), and `ProcessAsync(json, null)` binds to the session overload with `json` as the session id and a null document, which throws `ArgumentNullException`. Write `Process(json)`, `Process(json, context: null)` or `ProcessAsync(json, context: null)`. -- **DTOs.** `JsonRequest`, `JsonResponse` and `JsonRpcException` are plain DTOs without Json.NET attributes. `JsonRequest.Params` is the active serializer's object model, so cast to `JObject`/`JArray` only when the Json.NET serializer is active. -- **SMD.** `SMD.Services` is an `SMDServiceCollection` (an `IDictionary`) instead of a `Dictionary`, and its setter is gone. Every mutation through it updates the dispatch table at once, so a removed method is unreachable immediately. `SMD.Types` is now `Dictionary>` and a process-wide registry (it was reset whenever a session was created). - -### Changes clients will see on the wire - -- **Version member.** The `jsonrpc` member is checked (`Config.VersionPolicy`, default `Lenient`): a missing member is still accepted, but `"jsonrpc":"1.0"` or a non-string value is now `-32600`. Set `Ignore` for the 1.x behaviour. -- **Parse errors.** Requests nested deeper than 64 levels are `-32700` (configurable per serializer, see [Nesting depth](#nesting-depth)). Invalid UTF-8 and non-strict JSON (unless the serializer is lenient) are `-32700` as well. -- **Batches.** The empty-batch error code is the spec's `-32600` (it was `3200`). Batches made only of notifications produce an empty response instead of `[]` with a dangling comma. A batch always answers with a JSON array when it produces at least one response; a one-request batch is no longer unwrapped to a bare response object. -- **Notifications.** A notification (a request without an `id`) never gets a wire response, whatever its outcome: method not found, binding failure or an exception in the method produce nothing on the wire (the error handler still runs server-side). An invalid request object is not a notification and still gets `-32600` with `"id":null`. -- **Exceptions.** An unhandled exception is `-32603` with `data: null` by default; 1.x sent the exception's type, message and stack trace. `Config.IncludeExceptionDetails = true` sends the full description; an error handler can author something in between. See [Exception disclosure](#exception-disclosure). -- **Conversion errors.** A parameter value the serializer cannot convert (`"abc"` for an `int`, `"not-a-guid"` for a `Guid`) is `-32602` with `data = {"reason":"conversion","parameter":…,"index":…,"expectedType":…}`; it was `-32603` with the exception. An exception of the same type thrown inside the method is still `-32603`. A type the built-in serializer cannot handle at all stays `-32603` (now a `NotSupportedException`). -- **Method not found.** `-32601`'s `data` is `{"method":""}` instead of the fixed sentence, and a method-not-found error for a notification now reaches the error handler (the wire still gets nothing). -- **Named parameters.** They are checked against the method's parameter list: a supplied name that matches no parameter, or a name supplied twice, is `-32602` (it used to be ignored, so `optional(int a = 9)` called with `{"typo":4}` returned 9). Defaults fill only the names that are absent. -- **Dates and non-finite numbers.** `DateTime` and `DateTimeOffset` are written the way Json.NET writes them by every serializer (fraction only when non-zero, `Z`/offset/nothing by `Kind`); `NaN` and the infinities are written as the quoted strings `"NaN"`, `"Infinity"`, `"-Infinity"` and read back from them. - -### Behaviour inside your server - -- **Async methods.** Task-returning methods are supported again through `ProcessAsync`, together with `ValueTask` and `ValueTask`. Synchronous `Process`/`ProcessSync` reject them at call time without invoking them. `async void` remains rejected at registration. See [Asynchronous methods and cancellation](#asynchronous-methods-and-cancellation). -- **Request id.** The invocation frame also carries the request id: `Handler.RpcRequestId()` / `JsonRpcContext.CurrentRequestId()`, `Handler.RpcRequestIdKind()` and `Handler.RpcRequestIdRaw()`, see [The request id](#the-request-id). -- **Binding.** `ServiceBinder.BindMethod(sessionId, name, delegate)` registers any delegate; it refuses a name that is already registered, unlike `Handler.RegisterFuction`, which keeps replacing silently. -- **Pre-process handlers.** A pre-process handler may replace `JsonRequest.Method`, `Params` or `Id`; the replaced request is what gets dispatched (as in 1.x). Assign a new `Params` value rather than editing the serializer's object model in place: a request the handler leaves untouched is dispatched straight from the request bytes. -- **Context.** `JsonRpcContext.Current()` / `Handler.RpcContext()` and `JsonRpcContext.SetException` are per invocation: a method that synchronously processes another request through `JsonRpcProcessor` gets its own context and exception state back afterwards. -- **Sessions.** A request for a session id that was never registered no longer creates the session; it answers `-32601`. Bind services or call `Handler.GetSessionHandler(sessionId)` before serving a session. `Config.SetBeforeProcessHandler(sessionId, …)` is now `Config.SetPreProcessHandler(sessionId, …)` (the old name still compiles, with an obsolete warning), and `Config.SetPostProcessHandler(sessionId, …)` exists. -- **`JsonRpcService`.** The AspNetCore host binds a subclass to the configured session even when that is the default session; a subclass can pass `base(false)` to skip binding itself. -- **`Handler.Handle(JsonRequest)`** still works; it round-trips the request through the serializer and the boxed path. +Most 1.x services run unchanged. [Upgrading from 1.x](docs/upgrading.md) lists the changes that break the build, the changes clients will see on the wire and the behaviour changes inside your server. Read the first list before you build and the second before you deploy next to existing clients. [CHANGELOG.md](CHANGELOG.md) is the record of every change per version. ## Versioning and support - **Versioning.** The 2.x packages follow [Semantic Versioning](https://semver.org/) for the public API and the wire behaviour documented here: a breaking change to either arrives only in a new major version. - **Releases.** The four packages are built from one repository, carry one version number and are released together; use matching versions. There is no release cadence. +- **Previews.** 2.0 ships as `2.0.0-preview.N` first. A preview is complete and tested, but the public API may still change between previews; the stable 2.0.0 follows once the API has settled. - **Tested** means the `net8.0` and `net10.0` test runs on Windows and Linux listed under [Requirements](#requirements). Other runtimes can load the `netstandard` assets and are not tested. - **Trimming** is unsupported until the library is annotated and that is validated in CI. - **1.x** receives no further releases. @@ -669,7 +642,7 @@ dotnet test AustinHarris.JsonRpcTestN The test suite runs its protocol cases once per serializer (built-in, Json.NET, System.Text.Json) plus the parser, dispatch, version-policy and Kestrel integration tests, on both `net8.0` and `net10.0`. Building a package project in Release produces its NuGet package in `bin/Release/`. The WebAssembly sample builds without the `wasm-tools` workload; add it for AOT. -`AustinHarris.JsonRpc.Client`, `AustinHarris.JsonRpc.Client.WP7`, `AustinHarris.JsonRpc.AspNet`, `JsonRpcTest` and `TestClient` are 1.x projects that are still in the tree but outside the solution; nothing in 2.0 is built from them. +`AustinHarris.JsonRpc.Client`, `AustinHarris.JsonRpc.AspNet`, `JsonRpcTest` and `TestClient` are 1.x projects that are still in the tree but outside the solution; nothing in 2.0 is built from them. ### Charts diff --git a/docs/serializers.md b/docs/serializers.md index b31e000..4e0142b 100644 --- a/docs/serializers.md +++ b/docs/serializers.md @@ -163,4 +163,4 @@ constructor, throws `NotSupportedException` from `Read` (it was `JsonRpcBindExce on the wire. For the complete list of protocol, error, batching, async, context and metadata changes, see -[Upgrading from 1.x](../README.md#upgrading-from-1x) in the main README. +[Upgrading from 1.x](upgrading.md). diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..158866d --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,35 @@ +# Upgrading from 1.x + +Most 1.x services run unchanged. Read the first list before you build, and the second before you deploy next to existing clients. + +## Changes that break the build + +- **Serializer.** `JsonRpcProcessor.Process(…, JsonSerializerSettings)` is gone from the core. Use `Config.SetSerializer(new NewtonsoftJsonRpcSerializer(settings))` from the Newtonsoft package, or the helper overloads there that take the settings. +- **Overloads.** The default-session string overloads that take a serializer take it first: `Process(serializer, json, context)` and `ProcessSync(serializer, json, context)`. `ProcessSync(sessionId, json, context, serializer)` makes `context` required, so `ProcessSync(json, null)` still means the default session. `Process` and `ProcessAsync` do not: `Process(json, null)` no longer compiles (it is ambiguous with the `JsonRpcStateAsync` overload), and `ProcessAsync(json, null)` binds to the session overload with `json` as the session id and a null document, which throws `ArgumentNullException`. Write `Process(json)`, `Process(json, context: null)` or `ProcessAsync(json, context: null)`. +- **DTOs.** `JsonRequest`, `JsonResponse` and `JsonRpcException` are plain DTOs without Json.NET attributes. `JsonRequest.Params` is the active serializer's object model, so cast to `JObject`/`JArray` only when the Json.NET serializer is active. +- **SMD.** `SMD.Services` is an `SMDServiceCollection` (an `IDictionary`) instead of a `Dictionary`, and its setter is gone. Every mutation through it updates the dispatch table at once, so a removed method is unreachable immediately. `SMD.Types` is now `Dictionary>` and a process-wide registry (it was reset whenever a session was created). + +## Changes clients will see on the wire + +- **Version member.** The `jsonrpc` member is checked (`Config.VersionPolicy`, default `Lenient`): a missing member is still accepted, but `"jsonrpc":"1.0"` or a non-string value is now `-32600`. Set `Ignore` for the 1.x behaviour. +- **Parse errors.** Requests nested deeper than 64 levels are `-32700` (configurable per serializer, see [Nesting depth](../README.md#nesting-depth)). Invalid UTF-8 and non-strict JSON (unless the serializer is lenient) are `-32700` as well. +- **Batches.** The empty-batch error code is the spec's `-32600` (it was `3200`). Batches made only of notifications produce an empty response instead of `[]` with a dangling comma. A batch always answers with a JSON array when it produces at least one response; a one-request batch is no longer unwrapped to a bare response object. +- **Notifications.** A notification (a request without an `id`) never gets a wire response, whatever its outcome: method not found, binding failure or an exception in the method produce nothing on the wire (the error handler still runs server-side). An invalid request object is not a notification and still gets `-32600` with `"id":null`. +- **Exceptions.** An unhandled exception is `-32603` with `data: null` by default; 1.x sent the exception's type, message and stack trace. `Config.IncludeExceptionDetails = true` sends the full description; an error handler can author something in between. See [Exception disclosure](../README.md#exception-disclosure). +- **Conversion errors.** A parameter value the serializer cannot convert (`"abc"` for an `int`, `"not-a-guid"` for a `Guid`) is `-32602` with `data = {"reason":"conversion","parameter":…,"index":…,"expectedType":…}`; it was `-32603` with the exception. An exception of the same type thrown inside the method is still `-32603`. A type the built-in serializer cannot handle at all stays `-32603` (now a `NotSupportedException`). +- **Method not found.** `-32601`'s `data` is `{"method":""}` instead of the fixed sentence, and a method-not-found error for a notification now reaches the error handler (the wire still gets nothing). +- **Named parameters.** They are checked against the method's parameter list: a supplied name that matches no parameter, or a name supplied twice, is `-32602` (it used to be ignored, so `optional(int a = 9)` called with `{"typo":4}` returned 9). Defaults fill only the names that are absent. +- **Dates and non-finite numbers.** `DateTime` and `DateTimeOffset` are written the way Json.NET writes them by every serializer (fraction only when non-zero, `Z`/offset/nothing by `Kind`); `NaN` and the infinities are written as the quoted strings `"NaN"`, `"Infinity"`, `"-Infinity"` and read back from them. + +## Behaviour inside your server + +- **Async methods.** Task-returning methods are supported again through `ProcessAsync`, together with `ValueTask` and `ValueTask`. Synchronous `Process`/`ProcessSync` reject them at call time without invoking them. `async void` remains rejected at registration. See [Asynchronous methods and cancellation](../README.md#asynchronous-methods-and-cancellation). +- **Request id.** The invocation frame also carries the request id: `Handler.RpcRequestId()` / `JsonRpcContext.CurrentRequestId()`, `Handler.RpcRequestIdKind()` and `Handler.RpcRequestIdRaw()`, see [The request id](../README.md#the-request-id). +- **Binding.** `ServiceBinder.BindMethod(sessionId, name, delegate)` registers any delegate; it refuses a name that is already registered, unlike `Handler.RegisterFuction`, which keeps replacing silently. +- **Pre-process handlers.** A pre-process handler may replace `JsonRequest.Method`, `Params` or `Id`; the replaced request is what gets dispatched (as in 1.x). Assign a new `Params` value rather than editing the serializer's object model in place: a request the handler leaves untouched is dispatched straight from the request bytes. +- **Context.** `JsonRpcContext.Current()` / `Handler.RpcContext()` and `JsonRpcContext.SetException` are per invocation: a method that synchronously processes another request through `JsonRpcProcessor` gets its own context and exception state back afterwards. +- **Sessions.** A request for a session id that was never registered no longer creates the session; it answers `-32601`. Bind services or call `Handler.GetSessionHandler(sessionId)` before serving a session. `Config.SetBeforeProcessHandler(sessionId, …)` is now `Config.SetPreProcessHandler(sessionId, …)` (the old name still compiles, with an obsolete warning), and `Config.SetPostProcessHandler(sessionId, …)` exists. +- **`JsonRpcService`.** The AspNetCore host binds a subclass to the configured session even when that is the default session; a subclass can pass `base(false)` to skip binding itself. +- **`Handler.Handle(JsonRequest)`** still works; it round-trips the request through the serializer and the boxed path. + +Every change is recorded per version in the [changelog](../CHANGELOG.md). diff --git a/icon.png b/icon.png new file mode 100644 index 0000000..ad9f08d Binary files /dev/null and b/icon.png differ diff --git a/site/build.py b/site/build.py index c769182..28a5e88 100644 --- a/site/build.py +++ b/site/build.py @@ -45,6 +45,10 @@ PAGES = [ ("index.html", "README.md", "JSON-RPC.NET", "Overview", "Guide", "A high performance JSON-RPC 2.0 server for .NET: bytes in, bytes out, pluggable serializers, Kestrel hosting."), + ("changelog.html", "CHANGELOG.md", "What is new", "What is new", "Guide", + "Release notes for every version: what 2.0 adds, changes, removes and fixes, and the 1.x history."), + ("upgrading.html", "docs/upgrading.md", "Upgrading from 1.x", "Upgrading from 1.x", "Guide", + "What a 1.x server must change to build against 2.0, what clients will see on the wire, and what behaves differently inside the server."), ("serializers.html", "docs/serializers.md", "Serializers", "Serializers", "Guide", "How the built-in, Json.NET and System.Text.Json serializers differ, and how to configure or write one."), ("aspnetcore.html", "AustinHarris.JsonRpc.AspNetCore/README.md", "ASP.NET Core hosting", "ASP.NET Core hosting", "Packages",