Skip to content

Commit 9d4e802

Browse files
committed
AUS-1016: document the embedded-host patterns and add samples/EmbeddedHost
The API usability review (docs/reviews/2026-09-28_api-usability-review.md) found that every host outside ASP.NET Core rediscovers the same things: a guest process needs a session of its own, the raw-connection reply stream carries no framing, JsonFramer returns -1 for two different conditions, application error codes belong outside the reserved range, the cancellation token may sit between JSON parameters, and there is no dispatch context for a thread that owns the state. samples/EmbeddedHost is three hosts over one service, each about a page: HttpListener (body limit, deadline, 204 for notifications), any Stream with newline-delimited documents and a separate write loop (named pipe in the sample), and a SynchronizationContext that runs every document on one thread. Its check mode runs all three against a client. The project is in the solution and the sample README is a page on the documentation site. README: sessions guidance leads with a named session for guests; the hosting section gains the embedded subsection and the framer's -1 semantics; the raw connection sections state that replies carry no newline or Content-Length; the -32000 examples become application codes with the reason; unknown named members, the token's position, the public read path for bound methods (MetaData.Services), the adapter pattern for the context, and the AOT constraint are documented where a reader meets them.
1 parent 4fd96dd commit 9d4e802

14 files changed

Lines changed: 626 additions & 12 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ on:
1111
- "AustinHarris.JsonRpc.Newtonsoft/README.md"
1212
- "AustinHarris.JsonRpc.SystemTextJson/README.md"
1313
- "samples/WasmHost/README.md"
14+
- "samples/EmbeddedHost/README.md"
1415
- "benchmarks/Micro/README.md"
1516
- "benchmarks/charts/**"
1617
- ".github/workflows/pages.yml"

‎AustinHarris.JsonRpc.AspNetCore/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,10 @@ builder.WebHost.ConfigureKestrel(k =>
138138

139139
Clients write JSON documents back to back (whitespace or newlines between them are fine) and read the responses
140140
in the same order, also back to back with no newline or `Content-Length` prefix, so the client must parse one
141-
complete JSON value at a time. Notifications produce nothing. The `ConnectionContext` is the RPC context.
141+
complete JSON value at a time. A client that expects newline-delimited or `Content-Length`-framed replies (an LSP
142+
or MCP stdio client) is not served by this handler; a host that adds the framing over any `Stream` is in
143+
[samples/EmbeddedHost](../samples/EmbeddedHost). Notifications produce nothing. The `ConnectionContext` is the RPC
144+
context.
142145

143146
The framer accepts strict JSON only, even with the Json.NET serializer or a lenient `JsmnSerializer` selected.
144147
A document larger than `MaxRequestBytes` aborts the connection. Documents on one connection are processed one at

‎AustinHarris.JsonRpc.sln‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{5D20
2323
EndProject
2424
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WasmHost", "samples\WasmHost\WasmHost.csproj", "{293EB57E-ED38-4127-879C-34FD73820127}"
2525
EndProject
26+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EmbeddedHost", "samples\EmbeddedHost\EmbeddedHost.csproj", "{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}"
27+
EndProject
2628
Global
2729
GlobalSection(SolutionConfigurationPlatforms) = preSolution
2830
Debug|Any CPU = Debug|Any CPU
@@ -175,12 +177,33 @@ Global
175177
{293EB57E-ED38-4127-879C-34FD73820127}.Release|x86.Build.0 = Release|Any CPU
176178
{293EB57E-ED38-4127-879C-34FD73820127}.Release|x64.ActiveCfg = Release|Any CPU
177179
{293EB57E-ED38-4127-879C-34FD73820127}.Release|x64.Build.0 = Release|Any CPU
180+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
181+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|Any CPU.Build.0 = Debug|Any CPU
182+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|ARM.ActiveCfg = Debug|Any CPU
183+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|ARM.Build.0 = Debug|Any CPU
184+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
185+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|Mixed Platforms.Build.0 = Debug|Any CPU
186+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|x86.ActiveCfg = Debug|Any CPU
187+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|x86.Build.0 = Debug|Any CPU
188+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|x64.ActiveCfg = Debug|Any CPU
189+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Debug|x64.Build.0 = Debug|Any CPU
190+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|Any CPU.ActiveCfg = Release|Any CPU
191+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|Any CPU.Build.0 = Release|Any CPU
192+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|ARM.ActiveCfg = Release|Any CPU
193+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|ARM.Build.0 = Release|Any CPU
194+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
195+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|Mixed Platforms.Build.0 = Release|Any CPU
196+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|x86.ActiveCfg = Release|Any CPU
197+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|x86.Build.0 = Release|Any CPU
198+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|x64.ActiveCfg = Release|Any CPU
199+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11}.Release|x64.Build.0 = Release|Any CPU
178200
EndGlobalSection
179201
GlobalSection(SolutionProperties) = preSolution
180202
HideSolutionNode = FALSE
181203
EndGlobalSection
182204
GlobalSection(NestedProjects) = preSolution
183205
{293EB57E-ED38-4127-879C-34FD73820127} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
206+
{7A4C1E52-9B3D-4F61-8E2A-5C0D7B9F3A11} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
184207
EndGlobalSection
185208
GlobalSection(TestCaseManagementSettings) = postSolution
186209
CategoryFile = AustinHarris.JsonRpc.vsmdi

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ behaviour: a breaking change to either means a new major version.
2828
- `AddJsonRpcService<T>(ServiceLifetime, sessionId)` and the matching `AddJsonRpcServicesFromAssembly` overload: scoped and transient services are resolved per call from `HttpContext.RequestServices`, or from a scope the raw connection handler opens per document and publishes as `IServiceProvidersFeature`; a batch shares one scope. `JsonRpcOptions.ServiceProviderSelector` locates the provider from a custom context. A lifetime that conflicts with the container's registration, a non-singleton `JsonRpcService` subclass, and a `ContextFactory` without a selector are refused at registration or startup.
2929
- `protected JsonRpcService(bool autoBind)`: a subclass constructed with `base(false)` binds itself nowhere, for services that a host or an explicit `BindService` call binds.
3030
- `SECURITY.md` (private vulnerability reporting) and this changelog.
31+
- [samples/EmbeddedHost](samples/EmbeddedHost): the core hosted without ASP.NET Core, through `HttpListener`, over a named pipe with newline-delimited documents, and on a thread that owns the state; its `check` mode runs all three against a client.
3132
- `TestServer_Console --scale` is the release gate for the `ProcessAsync` path. It measures the inline rows at 1, 2 and N workers in three paired runs, takes the medians and fails when N/1 is below the threshold. `--kestrel [seconds] async` runs the host with `EnableAsyncMethods = true`. The README adds `--async` rows for `ProcessAsync` at 1 and 16 workers. The 1.x string overloads' thread-pool benchmark is now the `t` menu entry and no longer the default.
3233
- `--scale` prints per-serializer and yielding-row diagnostics after the gate; the Kestrel `EnableAsyncMethods = true` row with methods that suspend once is a release-required regression row: re-measured before each release against the previous release's figure, with no absolute floor.
3334

0 commit comments

Comments
 (0)