Skip to content

Commit c15849c

Browse files
committed
Rework README narrative and move API detail into reference
1 parent 42b736a commit c15849c

8 files changed

Lines changed: 600 additions & 557 deletions

File tree

‎README.md‎

Lines changed: 103 additions & 554 deletions
Large diffs are not rendered by default.

‎SECURITY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,6 @@ alongside it.
1919

2020
## What the library does and does not do
2121

22-
The README's [Security](README.md#security) section lists what the library does by default (exception redaction, nesting limit, document and batch limits in the core, request-size limit on the Kestrel host) and what it leaves to the host.
22+
The [security reference](docs/reference.md#security) lists what the library does by default (exception redaction, nesting limit, document and batch limits in the core, request-size limit on the Kestrel host) and what it leaves to the host.
2323

2424
Authentication, connection identity, TLS, rate limiting, request logging and deadlines belong to the host. HTTP hosts use ASP.NET Core middleware and endpoint metadata (`RequireAuthorization`, `UseRateLimiter`, the request-timeouts middleware); raw connections bypass that pipeline, so listen on loopback or a Unix socket, authenticate in front of them and use listener limits. Methods enforce authorisation that depends on parameter values. Core limits constrain admitted documents and batches, while transports bound bytes during receipt. Authentication and credential handling remain application responsibilities.

‎docs/reference.md‎

Lines changed: 489 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/serializers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ System.Text.Json API next to a lenient Json.NET one for old clients; the AspNetC
6363
`MapJsonRpc(pattern, options)` overload maps one endpoint per session). Use per-call when the transport
6464
negotiates it (a header, a route, a protocol version). The process-wide default is for the common case
6565
of one serializer everywhere. This order applies to the serializer only; error and processing handlers
66-
are per session, see the main README's [Configuration](../README.md#configuration) table.
66+
are per session, see the API reference's [Configuration](reference.md#configuration) table.
6767

6868
Construct a serializer once and share it: serializers must be thread-safe. The synchronous fast path
6969
keeps an envelope reader in per-thread scratch storage, reused while the serializer instance stays the

‎samples/EmbeddedHost/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,4 @@ dotnet run -- ui # the pipe host, methods run on the owning thread
2424
curl -s -X POST http://127.0.0.1:5078/rpc/ -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}'
2525
```
2626

27-
The README's [Hosting](../../README.md#hosting) section walks through the three files.
27+
The [embedded hosting reference](../../docs/reference.md#embedded-http-without-aspnet-core-a-pipe-without-kestrel-a-thread-that-owns-the-state) walks through the three files.

‎site/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ The pages at https://astn.github.io/JSON-RPC.NET/ are built from the Markdown fi
55
| Page | Source |
66
| --- | --- |
77
| Overview | `README.md` |
8+
| API reference | `docs/reference.md` |
89
| Serializers | `docs/serializers.md` |
910
| ASP.NET Core hosting | `AustinHarris.JsonRpc.AspNetCore/README.md` |
1011
| Json.NET serializer | `AustinHarris.JsonRpc.Newtonsoft/README.md` |

‎site/build.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545
PAGES = [
4646
("index.html", "README.md", "JSON-RPC.NET", "Overview", "Guide",
4747
"A high performance JSON-RPC 2.0 server for .NET: bytes in, bytes out, pluggable serializers, Kestrel hosting."),
48+
("reference.html", "docs/reference.md", "API and hosting reference", "API reference", "Guide",
49+
"Detailed binding, hosting, async, session, configuration and security behavior for JSON-RPC.NET."),
4850
("changelog.html", "CHANGELOG.md", "What is new", "What is new", "Guide",
4951
"Release notes for every version: what 2.0 adds, changes, removes and fixes, and the 1.x history."),
5052
("upgrading.html", "docs/upgrading.md", "Upgrading from 1.x", "Upgrading from 1.x", "Guide",

‎site/page.typ‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@
3636
img: ("void", (attrs) => himg(attrs.at("src", default: ""), alt: attrs.at("alt", default: ""))),
3737
picture: (attrs, body) => html.elem("picture", body),
3838
source: ("void", (attrs) => html.elem("source", attrs: attrs)),
39+
details: (attrs, body) => html.elem("details", body, attrs: attrs),
40+
summary: (attrs, body) => html.elem("summary", body, attrs: attrs),
3941
),
4042
)
4143

0 commit comments

Comments
 (0)