Hosting Papyr in your own app
Three calls put the relay into an ASP.NET Core app of your own, beside its routes and behind its sign-in. There is no
NuGet package: reference the project src/Papyr.AspNetCore. Its only public type is PapyrHostingExtensions, in
the namespace Papyr.AspNetCore. A complete, tested app of about 100 lines is
samples/PapyrSample.
src/Papyr.AspNetCore is under the FSL-1.1-ALv2 (the repository’s LICENSE): any app may host the relay, but not
one that is a commercial product or service offering what Papyr offers. The sample’s own code is MIT.
builder.Services.AddPapyr(builder.Configuration); // reads the Papyr:* settings, adds the rooms
var app = builder.Build();
app.MapPapyrRelay().RequireAuthorization(); // GET /relay, behind your sign-in
app.MapPapyrAdmin(); // the admin API under /api, off without a token
What each call does
AddPapyr(services, configuration), once, before the app is built. ReadsPapyr:DataDirectory,FlushIntervalSeconds,RoomExpiryDays,Relay:*,Blobs:*,Admin:*andBackup:*fromconfiguration(configuration.md) and throwsInvalidOperationExceptionnaming the setting and the fix when one is invalid. There is no options object: set a key in the configuration, in code too (builder.Configuration["Papyr:DataDirectory"] = ...). ATimeProviderorArrayPool<byte>registered before is used. The host locks the data directory when it starts: one another server holds, or that cannot be created, stops the start. When the app begins to stop, the rooms close their connections (1001) and flush.MapPapyrRelay(endpoints):GET /relay, relative to what you call it on (app.MapGroup("/collab")serves/collab/relay; the pages of Papyr.Server connect to/relay). There is no room in the path: a client names its room in its hello, the first message inside the WebSocket (relay-protocol.md). It returns the endpoint’s builder: addRequireAuthorization(),RequireHost(...)or a CORS policy. The endpoint runs its own WebSockets middleware (ping every 15 s); one your app has does no harm. It is mapped forGET(HTTP/1.1) andCONNECT(a WebSocket over HTTP/2, which browsers open on Kestrel’s HTTPS endpoints by default), and also maps/relay/{one segment}, where a page of version 1 still connects and is told to reload (4009, reasonversion1intelemetry.md). What you add to the builder applies to all of them. WithPapyr:Blobs:Enabled(off by default) it also maps the blob routes under/blobbeside the relay (relative to the same endpoints:/collab/blob): the upload and download of a room’s encrypted files andHEAD /blob, with the limits ofrelay-protocol.md, “Blobs”. What you add to the builder applies to them as well. Off, nothing is mapped and every path under/blobis yours. The routes take the room’s access key in the request headerPapyr-Room, so a gate of yours decides who may reach the server, not which room; they answer 403 to a foreignOriginas the relay does and send no CORS header. Never log or forward that header.MapPapyrAdmin(app): the admin API (admin-api.md) under/api, which cannot be moved (the admin page and the OpenAPI document name it). Its token check is inside every route and cannot be replaced or switched off; conditions on the returned builder (RequireHost("localhost:*")) run in front of it. Without a token it maps nothing.
What your app must do
- Sign-in in front of the relay. The relay takes whoever reaches it. A gate on its builder applies to the relay as a whole: the room is known only from the hello, after the upgrade, so no gate can admit a visitor to one room and not another (the room’s access key does that). It is checked at the upgrade only: a session that ends later does not close an open socket.
- The
Origin. A browser sends your visitor’s cookies with a WebSocket request that another site’s page opens, so a cookie gate alone would let that page in. The relay answers 403, before the upgrade, to a request whoseOriginnames neither the request’s own host (itsHost, same port) nor an origin inPapyr:Relay:AllowedOrigins(configuration.md; the exact rule:relay-protocol.md, “TheOrigin”). Pages your app serves need no entry; list pages elsewhere (another host or port, an installed client’sapp://...) as a browser writes them, without a default port. A request withoutOrigin(no browser, so no cookie) passes.SameSite=Stricton the cookie is the first defence, theOrigincheck the second. - Behind a proxy:
Hostand the scheme. The own host is theHostheader as the app sees it, so the proxy must pass the one the browser sent, port included (nginx:proxy_set_header Host $http_host; Caddy and Traefik pass it; YARP only withRequestHeaderOriginalHost). A proxy that rewrites it has every page refused, with event 33 once per start. If your app appliesX-Forwarded-Host(UseForwardedHeaders, from the proxy only), the forwarded host is the own host. “Over TLS” isHttpRequest.IsHttps: true when Kestrel terminates TLS, and behind a TLS proxy only when the app appliesX-Forwarded-Proto; then anhttp://origin is refused. Without it the scheme is not compared. Papyr.Server appliesX-Forwarded-Foronly. - A private network:
AllowedHosts. DNS rebinding points an attacker’s name at your server; the browser then sends that name inHostandOriginalike, so theOriginrule passes it. Such a page gets no cookie of yours, but a server on a private network should still answer its own names only: set ASP.NET Core’sAllowedHosts(AllowedHosts=notes.internal,;-separated; Papyr.Server takes it too), which answers 400 to any otherHost. - Forwarded headers. Behind a proxy, apply its
X-Forwarded-For(UseForwardedHeaderswithKnownProxiesorKnownIPNetworksset to that proxy,ForwardLimit1) before the endpoints: the relay counts its limits per client address, and without it every client is one source (event 19 once). Never trust every peer (ASPNETCORE_FORWARDEDHEADERS_ENABLED=true). - Request bodies. An upload sets
MaxRequestBodySizeof its own request toPapyr:Blobs:BlobBytesas its first statement, before anything reads the body, so a limit of your app or of Kestrel cannot lower it: setBlobBytesto what you want to take. An upload that declares more is refused with 413 and the app reads none of its body (Kestrel drains an unread body for up to 5 seconds after the answer, so that such a request still costs its bandwidth until then). The body is streamed to a file through Kestrel’s input buffer, within 10 seconds and one more per 256 KiB of its length, else the connection is ended. Blobs are stored inblobs/of the data directory, besiderooms/and under the same lock; they count in the disk you give it (configuration.md). - Kestrel. The façade changes none of its options. Papyr.Server sets
Limits.MaxRequestBufferSizeand the socket transport’sMaxReadBufferSizeto 64 KiB (they default to 1 MiB, which every relay connection could hold),MaxConcurrentUpgradedConnectionstoPapyr:Relay:ServerConnections, and a 15 s keep-alive timeout: do the same where memory matters (configuration.md, “Memory”). - Order of the middleware. Call
MapPapyrAdminafterUseForwardedHeadersand before your static files or any fallback that would answer a path under/api; if you callUseRouting()yourself, call it beforeMapPapyrAdmin. - Telemetry and logs. An
ActivitySourceand aMeternamedPapyr(telemetry.md); events go through yourILoggerunder the categoriesPapyr.AspNetCore.*.
What it changes in your app
AddPapyr with an admin token puts the admin types’ JSON context first in the resolver chain of your HTTP JSON options
(the OpenAPI package reads them). It resolves those types and no others, so nothing else your app serializes changes.
No other global setting is touched.