Skip to content

AUS-1016: embedded-host docs bundle and samples/EmbeddedHost - #175

Merged
Astn merged 1 commit into
masterfrom
aus-1016-docs
Sep 28, 2026
Merged

Astn merged 1 commit into
masterfrom
aus-1016-docs

Conversation

@Astn

@Astn Astn commented Sep 28, 2026

Copy link
Copy Markdown
Owner

Docs bundle from the API usability review, plus the sample it points at. No library code changes.

samples/EmbeddedHost (in the solution, not packed): the core hosted without ASP.NET Core.

  • HttpListenerHost.cs: HTTP through System.Net.HttpListener; body limit, a deadline the host arms itself (504 when it fires), 204 for a notification, 405 for anything but POST.
  • StreamHost.cs: any Stream (a named pipe here) with newline-delimited documents both ways, framed with JsonFramer, a bounded buffer, documents run one at a time in order, and a separate write loop fed by a queue so pipelined clients cannot deadlock. Server-side events go out as notifications on the same queue. The -1 from FindDocumentEnd is disambiguated so garbage answers -32700 and closes instead of stalling.
  • UiThread.cs: a SynchronizationContext over one thread; every document and every continuation inside a method runs there.
  • dotnet run -- check runs all three in process against a client; twelve checks, exit code 0. Run locally: all pass.

README

  • Sessions: a guest in someone else's process (plugin, add-in, library) names a session of its own; the reason is spelled out.
  • Defining methods: unknown named members are refused with -32602, never dropped. New "Reading what is bound" paragraph for MetaData.Services / RpcMethod / dele.
  • Hosting: the framer's -1 semantics and buffer bounding; a new "Embedded" subsection walking the three sample files; the raw-connection paragraph now says replies carry no newline and no Content-Length (same in the AspNetCore README).
  • Errors: the -32000 examples become application codes (1000, 1001) with the reason: the specification reserves -32768..-32000.
  • Cancellation: the token parameter may sit anywhere in the signature, so (int id, [JsonRpcCancellation] CancellationToken token, int limit = 10) is the natural shape.
  • Context: the adapter pattern (pass the transport object, read it before the first await, cast to an interface to stay transport-neutral).
  • Installation and Versioning: trimming/AOT is the one constraint that keeps a host off 2.0 until the 2.8 generator.

Site: the sample README is a page ("Embedded host sample", under More); local Typst build reports no missing anchors or files. CHANGELOG has an Added entry.

Linear: AUS-1016.

…dHost

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.
@Astn
Astn merged commit 42b736a into master Sep 28, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant