The page contract

All assemblies · uk.osric.asp.Sdk · 57 types · 340 entries

uk.osric.asp.Sdk

HttpFetchFailure

Why a fetch did not produce a usable response.
A fetch failure is a value, not an exception, so a page that shows live data can fall back without a try. An HTTP error is a failure even though the remote server answered: the page still gets the real status, so a 500 is distinguishable from a 404.

FieldNone

The request completed and the remote server answered.

FieldInvalidRequest

The URL, method, body, a header or a redirect target was not acceptable. No connection was made to it.

FieldTimeout

The per-fetch timeout or the render's deadline fired.

FieldAborted

The request was cancelled, or the render was abandoned.

FieldNetwork

DNS, connect, TLS or protocol failure.

FieldHttpError

The remote server answered with a 4xx or 5xx; Status names it.

FieldTooManyRequests

This render has already made as many requests as it may.

FieldTooManyRedirects

The redirect limit was reached; Status is the last 3xx.

HttpFetchMethod

The method an outbound fetch uses.

FieldGet

A request with no body.

FieldPost

A request that may carry a text body.

HttpFetchRequest

An outbound HTTP request a page asks the host to make.
The host makes the request, not the browser, to any http or https host the URL names. Credentials in the URL are refused. A page that needs one names an operator-configured credential with Credential; the header allow-list still admits Authorization and X- headers for a value the page itself already holds.

MethodHttpFetchRequest(string Url)

An outbound HTTP request a page asks the host to make.
The host makes the request, not the browser, to any http or https host the URL names. Credentials in the URL are refused. A page that needs one names an operator-configured credential with Credential; the header allow-list still admits Authorization and X- headers for a value the page itself already holds.

Parameters

Url
An absolute http or https URL, with no credentials and no fragment.

PropertyUrl

An absolute http or https URL, with no credentials and no fragment.

Exceptions

ArgumentException
The URL is blank.

PropertyMethod

The method; Get by default.

PropertyBody

The request body. POST only, and text only.

PropertyHeaders

Additional request headers. The host filters and validates them: a small allow-list of names plus any X- name, and no line breaks.

PropertyCredential

The name of an operator-configured credential the host attaches to this request.

A name, never a value: the page never sees the value.

The host sends the credential only to the host it is configured for, and only from the page it is bound to. It drops the header on a redirect to another host or to plaintext. A page that does not know a credential name asks the operator rather than inventing one; an unknown name is an InvalidRequest and no request is made.

null, the default, means no credential.

HttpFetchResponse

What an outbound fetch produced.
Every transport outcome is a value, so a page that shows live data can branch on Failure instead of catching. On a transport failure Status is 0, the headers and body are empty and Truncated is false. An HTTP error response keeps its real status, so a page can test Status >= 500 or a specific code such as 404.

MethodHttpFetchResponse(int Status, IReadOnlyDictionary<string, string> Headers, string Body, HttpFetchFailure Failure, bool Truncated)

What an outbound fetch produced.
Every transport outcome is a value, so a page that shows live data can branch on Failure instead of catching. On a transport failure Status is 0, the headers and body are empty and Truncated is false. An HTTP error response keeps its real status, so a page can test Status >= 500 or a specific code such as 404.

Parameters

Status
The HTTP status, or 0 when no response was received.
Headers
The response headers the host returns: a small allow-list plus any X- name.
Body
The response body decoded as text, possibly truncated.
Failure
Why the fetch failed, or None.
Truncated
Whether the body hit the host's response cap.

PropertyStatus

The HTTP status, or 0 when no response was received.

PropertyHeaders

The response headers the host returns: a small allow-list plus any X- name.

PropertyBody

The response body decoded as text, possibly truncated.

PropertyFailure

Why the fetch failed, or None.

PropertyTruncated

Whether the body hit the host's response cap.

PropertySucceeded

Whether this was a 2xx response with no transport or HTTP failure.

HttpFetchStream

A bounded, line-oriented text response from an outbound HTTP request.
A null line means the response ended. Failure and Truncated explain whether it ended normally or was cut short. The stream occupies the same bounded outbound-fetch budget as a buffered request and must be closed when it is no longer needed.

MethodHttpFetchStream()

Initializes a stream implementation.

PropertyStatus

The HTTP status, or zero when no response was received.

PropertyHeaders

The response headers exposed by the host.

PropertyFailure

Why the request or stream ended, or None.

PropertyTruncated

Whether a timeout, transport failure or configured byte cap ended the body early.

MethodReadLineAsync()

Reads the next decoded line, or returns null when the stream has ended.

Returns

The next line without its line terminator, or null at end of stream.

MethodCloseAsync()

Closes the response and releases its connection.

Returns

A task that completes when the response is closed.

IBuildInfo

The build that is answering the request.
This is a capability because a page may not read the assembly or the environment: the page API denies both. A build made outside a checkout records no commit, so Commit is null rather than a placeholder a page might mistake for a hash.

PropertyCommit

The full git commit hash, or null when the build has none.

IContext

What a page can read from the request and ask of the response.

This is the whole contract a stored page is written against, and the only type a page sees that touches the request. Everything on it is a plain value, so the runtime never hands page code an ASP.NET type.

This is the request side of the contract: what a page can read and ask for. What it writes into is Response, an IPageResponse, and that is where the buffering and the commit rule live.

The handler is asynchronous, so await is an ordinary expression in a code block and inside a write expression. Every member that does I/O — here or on a capability reached through Capabilities — returns a Task and takes no cancellation token: the render owns Aborted and the deadline, and the implementation links them per call.

PropertyRequest

The request the page is running against.

PropertyPath

The canonical key of the page being rendered.

PropertyEditorPath

The canonical key of the site's editor page, so a page can link to it.
The editor's key is the host's policy — Pages:Editor:Key — so a page that hard-codes it breaks when the owner moves the editor. The editor's own page is served at this key and takes the page to edit as ?edit=, which makes ctx.EditorPath + "?edit=" + System.Uri.EscapeDataString(ctx.Path) the way to offer "edit this page".

PropertyUser

The signed-in local account, or null for an anonymous visitor.
The identity is supplied and validated by the shell; a page cannot forge it with a header, cookie or form field. A page is public unless its own code checks this value, so the ordinary guard is if (ctx.User is not { } user) { ctx.Response.RedirectToLogin(); return; }.

PropertyAborted

Aborted when the request is abandoned; pages may observe it to stop early.

PropertyResponse

What the page writes into: its body, the settings applied to it and the response shapes.
This is not a capability. Every page always has a response, so it is on the context; a page that needs none of the rest still needs this.

MethodLog(string message)

Logs a message at information level.
Entries are filed under a category shared by every page, with Path on a scope, so a page's lines can be filtered or levelled without touching another page's.

Parameters

message
The message to log.

MethodLogWarning(string message)

Logs a message at warning level.

Parameters

message
The message to log.

MethodLogError(string message)

Logs a message at error level.

Parameters

message
The message to log.

MethodAssetUrl(string href)

Versions a same-origin link when the page it names is a live asset.
An asset is a page with no code: a complete representation whose source is the response. The hash pins the retained revision, so editing the asset does not change a URL that already points at it.

Parameters

href
The link as the page would write it.

Returns

The link with a ?v= hash, or the link unchanged when it is not a bare site-relative path or does not name a live asset. A query or fragment, an absolute or protocol-relative URL and a missing, deleted or compiled page all keep the link as written, so an unversioned fallback still works.

PropertyCapabilities

The capabilities this render offers.
Storage, outbound HTTP, the document's slots and Markdown live here rather than on the context, because a page that needs none of them should never meet them. A capability the render does not offer is absent rather than null; a page decides whether that is fatal with Get<T> or GetRequired<T>.

MethodWriteRaw(string message)

Writes unescaped HTML to the output. Deprecated: use Response.

Parameters

message
The HTML to write.

MethodWrite(string message)

Writes escaped HTML to the output. Deprecated: use Response.

Parameters

message
The text to escape and write.

MethodFlushAsync()

Sends what has been written so far and commits the response. Deprecated: use Response.

Returns

A task that completes when the bytes have been handed to the response.

MethodSetStatus(int status)

Sets the response status code. Deprecated: use Response.

Parameters

status
The code to send, between 100 and 599.

MethodSetContentType(string contentType)

Sets the response content type. Deprecated: use Response.

Parameters

contentType
The media type to send.

MethodSetHeader(string name, string value)

Sets a response header the page is allowed to control. Deprecated: use Response.

Parameters

name
The header name.
value
The header value; it may not contain a line break.

MethodAllowScripts()

Allows this page to load same-origin scripts. Deprecated: use Response.

MethodRedirect(string location, int status)

Redirects instead of writing a body. Deprecated: use Response.

Parameters

location
The target, relative or absolute.
status
The redirect status; 302 by default.

MethodRedirectToLogin()

Sends an anonymous visitor to the sign-in form. Deprecated: use Response.

PropertyAntiforgeryField

The hidden input that carries this request's antiforgery pair. Deprecated: use Response.

IDiffRenderer

Renders the line changes between two documents as HTML for a stored page.

The renderer is reached through Capabilities as ctx.Capabilities.GetRequired<IDiffRenderer>(), and its result is written raw: <%== diff.ToHtml(before, after) %>. It supports the line changes a page can compare with IPageCatalog: two templates, two revisions, or any two strings the page has.

This is not Markdown. Every source line is escaped, so a page may pass a visitor's text, a fetched body or page state without turning it into markup. The result is a table.diff with one row per changed or context line, a tr.diff-hunk header per hunk, and a div.diff-scroll that scrolls sideways and takes focus; an unchanged pair writes p.diff-empty, and a pair too different to align writes p.diff-coarse before the table.

Rendering is pure: it has no I/O, needs no await, and is bounded by the render's body allowance when the result is written. The diff itself is bounded by the host's line and edit caps; past them the middle is shown as replacement blocks rather than the work being left unbounded.

MethodToHtml(string before, string after)

Renders a line diff of two documents as HTML.

Parameters

before
The earlier document.
after
The later document.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
Either document is null.

IHandler

The entry point of a compiled page.

MethodHandleAsync(IContext context)

Runs the page against the request context.
The host awaits the returned task; the response is shaped from the context once it completes. A page that calls FlushAsync commits the response earlier, and the rest of the body is sent as it is written. A page must not start work it does not await, because nothing else in the render waits for it and the answer may already have been given when it finishes.

Parameters

context
The context the page reads and writes through.

Returns

A task that completes when the page has finished.

IHttpFetch

Makes bounded outbound HTTP requests.
One capability, three call sites: the two conveniences cover the ordinary case and are default interface members over the general form, so a host implements one method and a new HTTP verb stays a value in HttpFetchMethod rather than a new member here.

MethodSendAsync(HttpFetchRequest request)

Makes one bounded outbound HTTP request.

Parameters

request
The request to make.

Returns

The response. A failure is a value, not an exception.

MethodStreamAsync(HttpFetchRequest request)

Makes an outbound HTTP request whose text response can be read one line at a time.

Parameters

request
The request to make.

Returns

The response stream. A transport failure is reported through its values, not an exception.

MethodGetAsync(string url)

Makes a GET request.

Parameters

url
An absolute http or https URL.

Returns

The response. A failure is a value, not an exception.

MethodPostAsync(string url, string body)

Makes a POST request with a text body.

Parameters

url
An absolute http or https URL.
body
The text body; the host sends it as text/plain unless a header says otherwise.

Returns

The response. A failure is a value, not an exception.

IMarkdownRenderer

Renders Markdown to HTML for a stored page.

The renderer is reached through Capabilities as ctx.Capabilities.GetRequired<IMarkdownRenderer>(), and its result is written raw: <%== markdown.ToHtml(source) %>. It supports CommonMark, pipe tables, auto-links and the links and images Markdown can express. Each heading carries an id derived from its text, so a page can link to a section; MarkdownOptions switches that, auto-links and pipe tables per call.

This is not a sanitiser. Raw HTML in the Markdown passes through, exactly like WriteRaw, and a link's scheme is not restricted. A page author may write HTML directly, so that is no more authority than the template already has — but text from a visitor, a fetch or storage is data, not markup. Escape it with Write rather than rendering it.

Rendering is pure: it has no I/O, needs no await, and is bounded by the render's body allowance when the result is written.

MethodToHtml(string markdown)

Renders a Markdown document to HTML with the page profile.

Parameters

markdown
The Markdown to render. Raw HTML in it is passed through.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
markdown is null.

MethodToHtml(string markdown, MarkdownOptions options)

Renders a Markdown document to HTML with the features the page chooses.

Parameters

markdown
The Markdown to render. Raw HTML in it is passed through.
options
The features to switch on or off for this render.

Returns

The HTML to write with WriteRaw or <%== %>.

Exceptions

ArgumentNullException
markdown or options is null.

IPageCapabilities

The optional capabilities this render offers.
Read-only: a page asks, and the host has already decided. A capability is either registered with an implementation or absent — never registered as null.

MethodTryGet<T>(ref T capability)

Reads a capability that this render may or may not offer.

Parameters

capability
The implementation, when this render offers the capability.

Returns

Whether this render offers the capability.

MethodGet<T>()

Reads a capability, or null when this render does not offer it.

MethodGetRequired<T>()

Reads a capability this page cannot render without.

Exceptions

InvalidOperationException
This render does not offer the capability.

IPageCatalog

A read-only view of the site's page store, and of the links the shell knows.

Four store reads, one list of shell links and no writes: a page can list the store, read a live page's template, read a page's history, read one retained revision and ask what the shell can do. It never meets an image, a symbol or a writable member; saving is a separate capability.

The read is as public as the page that calls it. There is no gate in the host, so an anonymous visitor gets the same answers a signed-in one does, and a page that wants its listing or its source private writes the ordinary guard: if (ctx.User is not { } user) { ctx.Response.RedirectToLogin(); return; }. Because the read is not gated, a page that calls ReadAsync or ReadRevisionAsync publishes the source it reads to whoever can reach that page.

Every store read returns a Task and takes no cancellation token, as IPageStorage and IHttpFetch do: the render owns Aborted and the deadline, and the implementation links them per call. A render that was abandoned, or a deadline that passed, throws when the returned task is awaited. ShellLinks is a value rather than a read, and refuses the same way.

The read is bounded. One listing returns at most the host's row cap and refuses rather than truncating, and every template the render pulls in shares one source allowance across the page and its layouts, which is also a refusal rather than a truncated answer.

The links the shell knows, as values a page may render.

It answers what the shell can do, not what the store holds: the links name shell routes and the editor's configured key, so a page cannot build them itself. The host returns the whole list and the page decides — it filters on ShellAudience with its own User, picks the section, orders, relabels, marks the current one and writes its own markup.

The sign-in link carries this request's way back, so a layout and the page it wraps see one answer. A worker's catalog has no request and no visitor, so it has no links.

Returns

Every link the shell can draw, both the site menu and the administration menu, each with the section it belongs to and the audience it is for. The order is the shell's reading order.

Exceptions

InvalidOperationException
The render was abandoned.

MethodListAsync(string prefix)

Lists the heads of the store, under a prefix.

Parameters

prefix
The subtree to list. "" and "/" are the whole store; any other value is normalised as a page key, so /Blog/ and /blog are the same request. A prefix lists the key itself and the keys beneath it, never a key that merely starts with the same text: /blog lists /blog and /blog/post, never /blogroll.

Returns

Every head under the prefix, including tombstones, seeded assets and reserved keys, ordered by key and marked so a view can pick what it wants.

Exceptions

ArgumentException
The prefix cannot name a key, for example one containing ? or #.
InvalidOperationException
The render was abandoned, or the prefix holds more rows than the host's listing cap; the message names the cap and suggests a prefix.

MethodReadAsync(string key)

Reads a live page's template.

Parameters

key
The page's key; normalised before it is read.

Returns

The page's current source with its hash and saved time, or null when no live page has that key. A tombstone is listed as deleted, and reads as absent.

Exceptions

ArgumentException
The key cannot name a page.
InvalidOperationException
The render was abandoned, or the source would take the render past its source allowance.

MethodRevisionsAsync(string key)

Lists one page's history, newest first.

Parameters

key
The page's key; normalised before it is read.

Returns

The page's revisions, including those of a tombstoned page: the history survives a delete by design. An unknown key is an empty list rather than an error.

Exceptions

ArgumentException
The key cannot name a page.
InvalidOperationException
The render was abandoned.

MethodReadRevisionAsync(string key, string hash)

Reads one retained revision's template.

Parameters

key
The page's key; normalised before it is read.
hash
The revision's hash, as RevisionsAsync reported it.

Returns

The revision's source with its hash and saved time, or null when that page has no revision with that hash. Both handles are required, so a hash remembered from one page cannot be spent on another.

Exceptions

ArgumentException
The key cannot name a page, or the hash is empty.
InvalidOperationException
The render was abandoned, or the source would take the render past its source allowance.

IPageComposition

What a page can render beside itself, and around itself.

Reached through Capabilities as ctx.Capabilities.GetRequired<IPageComposition>(), so a page that never composes never meets it. Every layer of a render is offered it, so a wrapper can embed a header and a footer partial, and a page can ask to be wrapped without knowing whether it is embedded.

An embedded page is a render of the whole page: its body, every wrapper it declares, its own key, storage and session, the caller's identity, one budget and one slot, and no response of its own. It is composition, not isolation: it has the capabilities a content page has, may write the store and may start a job.

A request is the input in both directions. null means the caller's own request; one that is given runs as it stands, except that Path is always the page the visitor asked for, which the host pins. PageRequestExtensions copies and changes a request without adding members to the record.

MethodEmbedAsync(string key, PageRequest request)

Renders another stored page where the call is, wrappers and all.
The frame is what the embedded page contributes outside its body, so a caller that wants its title, head or sheets folds them into its own slots. The call writes the outermost body, so a failure that is caught leaves nothing half-written.

Parameters

key
The embedded page's canonical key, such as /cards/post.
request
The request to run it against, or null for this page's.

Returns

The outermost layer's frame; the body has already been written.

Exceptions

ArgumentException
The key is not a page address.
InvalidOperationException
The page is already being rendered in this chain with the same request, or the render's depth or fan-out limit has been reached.
The key names no page, or one that cannot be served; the embedded page redirects; or its wrapper cannot be served.
OperationCanceledException
The render's deadline fired while it ran.

MethodCaptureAsync(string key, PageRequest request)

Renders another stored page, and returns its body instead of writing it.
The same render as EmbedAsync with the write left out, for a page that wants to transform another page's output, or keep it for later. Its script permission is not applied to this response: a caller that adopts the body calls AllowScripts itself when AllowsScripts says the body needs it.

Parameters

key
The captured page's canonical key.
request
The request to run it against, or null for this page's.

Returns

The outermost layer's body and frame; nothing was written.

Exceptions

ArgumentException
The key is not a page address.
InvalidOperationException
The page is already being rendered in this chain with the same request, or the render's depth or fan-out limit has been reached.
The key names no page, or one that cannot be served; the captured page redirects; or its wrapper cannot be served.
OperationCanceledException
The render's deadline fired while it ran.

MethodWrap(string key, PageRequest request)

Declares a page that wraps this one, outside any layer already declared.

A declaration, not a handover: the host runs the chain after the page returns, so a guard's early return; is still wrapped and the page can set its status after writing its body. Calls stack outward, so the first is the innermost layer this page names and each later call wraps the result of the previous one. A wrapper may add its own outside it.

The wrapper receives this layer's PageCapture as Content and decides what to fold. A page that declares nothing is served exactly as it wrote itself.

Parameters

key
The wrapper's canonical key, such as /_markdown.
request
The request to run the wrapper against, or null for this page's.

Exceptions

ArgumentException
The key is not a page address.
InvalidOperationException
The key is a reserved path, or the response has already been flushed.

MethodWrap()

Declares the site's layout as the page that wraps this one.
The key is the host's policy, so a page does not hard-code one the owner can move. When the site is configured with no default layout, this records nothing.

Exceptions

InvalidOperationException
The response has already been flushed.

IPageJobs

Starts and watches the jobs that run a stored worker.

A job is one run of a worker: it outlives the request that started it, so it has no response to write and no visitor waiting on it. This is the page's side of it — start one, talk to it, find it again, read what it published and stop it — and it is a capability rather than an IContext member, so a page that never wants one never meets it.

Nothing here names an owner. The handle is bound to the signed-in visitor who asked, every call is filtered to that visitor's jobs, and an anonymous render is refused a start rather than quietly given somebody else's work. Every refusal is a value.

MethodStartAsync(string workerKey, string firstMessage)

Starts one run of the worker stored at workerKey.

Parameters

workerKey
The canonical key of a stored worker.
firstMessage
The first message the worker receives, or null when it needs none. Bounded by Pages:Jobs:MaxMessageBytes.

Returns

The job's id, or the reason it was refused.

MethodSendAsync(string jobId, string message)

Sends a message to a running job.

Parameters

jobId
The id a start or a listing answered with.
message
The message text or JSON, bounded by Pages:Jobs:MaxMessageBytes.

Returns

Whether it was queued, or the reason it was refused.

MethodGetAsync(string jobId)

Reads one job, if this visitor owns it.

Parameters

jobId
The id a start or a listing answered with.

Returns

The job, or null when it is unknown or another visitor's.

MethodListAsync()

Lists this visitor's jobs, newest first.

Returns

The jobs this visitor started, in the order they were started.

MethodReadEventsAsync(string jobId, long after, double? waitSeconds)

Reads a job's events after a sequence, waiting briefly for the next one.

Parameters

jobId
The id a start or a listing answered with.
after
The last sequence the caller has already seen; 0 reads from the start.
waitSeconds
How long to wait for an event that has not arrived yet, capped by Pages:Jobs:MaxWaitSeconds and by the render's own budget. Omitted or null does not wait.

Returns

The events after after, or a reset when the journal no longer holds that sequence, with the job's state once it has ended.

MethodCancelAsync(string jobId)

Asks a job to stop.

Parameters

jobId
The id a start or a listing answered with.

Returns

Whether the job was there to stop, or was already finished.

IPageLayout

The slots one layer of a render owns, and the layer inside it.

Reached through Capabilities as ctx.Capabilities.GetRequired<IPageLayout>(), so IContext gains nothing for chrome and a page that never wants a layout never meets one.

The slots are this layer's own: the host does not fold the layer inside into them. A wrapper reads Content and decides what to fold with AddHead, AddStylesheet and Title, so the page that owns the document chooses in both directions.

A page is wrapped only if it asks: Wrap names the site's layout, and a page that asks for nothing is served exactly as it wrote itself.

It is not a guard. The content has already run by the time the wrapper starts, so a layout hides chrome; it cannot prevent a side effect.

A page that streams its response with FlushAsync is served alone: a layout needs the whole body before it can write its own, so a page that flushes is a page that declares no wrapper.

PropertyContent

The layer inside this one, when this is a wrapper; null otherwise.
The content's whole body, wrappers and all, beside the frame of the outermost layer inside this one. A wrapper that ignores it serves its own document and nothing of the content.

PropertyTitle

This layer's own document title, or null until it is set.
The setter refuses a blank title, so the only way to have none is to leave it unset, and a wrapper decides what a missing title from the layer inside it means.

Exceptions

ArgumentException
The title is blank.

PropertyHead

This layer's AddHead markup, in the order it was added.

PropertyStylesheets

This layer's sheets, in the order it added them.

MethodAddHead(string markup)

Adds raw markup to the document's head.

Parameters

markup
The markup to add; it is the caller's, not a request value.

MethodAddStylesheet(string href)

Links one stylesheet from the document.

Parameters

href
A site-relative URL, such as /blog.css. Called once per link; zero, one or many calls decide how many the document carries.

Exceptions

ArgumentException
The href is not a site-relative URL.

IPageResponse

What a page writes into: its body, the settings applied to it, and the response shapes.

Reached as ctx.Response. It is contract rather than a capability, because every page always has one; a helper can take this interface on its own to get the output and nothing else.

Status, content type and headers are applied after HandleAsync completes. The body is buffered until then, so a page that throws produces a clean error response rather than half a document. A page that calls FlushAsync opts into sending its body while it runs; from the first flush the response is committed and those settings are final.

MethodWriteRaw(string message)

Writes unescaped HTML to the output.

Parameters

message
The HTML to write.

MethodWrite(string message)

Writes escaped HTML to the output.

Parameters

message
The text to escape and write.

MethodFlushAsync()

Sends what has been written so far and commits the response.

The first flush is the commit point: the status, content type, headers and script policy are applied and the response starts, so they are final from then on. A later SetStatus, SetContentType, SetHeader, AllowScripts, Redirect or read of AntiforgeryField throws instead of silently doing nothing. Writes after a flush are buffered until the next flush, and whatever remains when the handler returns is sent then.

A page that flushes is served alone: a layout needs the whole body before it can run, so a flush while the page would be wrapped throws. Clear IPageLayout.Layout and write the page's own document first. A layout itself cannot flush.

Streaming does not change the escaping rule: Write still encodes and WriteRaw still writes the caller's markup. A page that fails after its first flush has no error page to fall back on; the response is truncated and the failure is logged. The render budget still applies, so a stream is ended at its deadline, and a HEAD request commits the response but sends no body.

The first flush is also where the render budget changes shape. Before it the render's whole budget applies; from it the response has its own silence and ceiling (Pages:Stream), the render slot is released and a stream slot is taken. A stream that goes quiet, or reaches its ceiling, is truncated; it is no longer cut by the render's timeout.

This takes no cancellation token, like every other I/O member of the page contract: the render owns Aborted and the deadline and links them per call.

Returns

A task that completes when the bytes have been handed to the response.

Exceptions

InvalidOperationException
The render cannot stream, the page is a layout, it has redirected, or it is still wrapped in a layout.
Every stream slot is taken, so nothing was committed. The shell answers 503 unless the page catches this and writes its own document.

MethodSetStatus(int status)

Sets the response status code.

Parameters

status
The code to send, between 100 and 599.

MethodSetContentType(string contentType)

Sets the response content type.

Parameters

contentType
The media type to send.

MethodSetHeader(string name, string value)

Sets a response header the page is allowed to control.

Parameters

name
The header name.
value
The header value; it may not contain a line break.

Exceptions

ArgumentException
The header is reserved to the shell, or the value cannot be sent safely.

MethodAllowScripts()

Allows this page to load same-origin scripts.
Widens the response's Content-Security-Policy from script-src 'none' to script-src 'self'. Inline scripts and event-handler attributes stay blocked, as do scripts from another origin: the page's script is another page, or a seeded asset, served with a JavaScript content type and referenced by <script src="/…">. Calling this more than once is harmless.

MethodRedirect(string location, int status)

Redirects instead of writing a body.

Parameters

location
The target, relative or absolute. A relative target keeps its query and fragment, and its path is escaped for the header, so /search?q=metrics arrives as written.
status
The redirect status; 302 by default.

MethodRedirectToLogin()

Sends an anonymous visitor to the sign-in form and back to this page afterwards.

The target is the shell's own: /login?returnUrl= followed by this page's canonical path and raw query, so the visitor returns to exactly what they asked for. A fragment is not preserved, because the browser never sends one.

The status is 302 Found for GET and HEAD, and 303 See Other for POST, so a submitted form is not replayed when the visitor comes back. This returns normally; a guard must also return; from the page.

PropertyAntiforgeryField

The hidden input that carries this request's antiforgery pair.

Write it raw, as <%== ctx.Response.AntiforgeryField %>, inside every form on a page an authenticated visitor can submit: the shell refuses an authenticated POST without a valid pair. It is generated once per render, so asking twice does not mint two tokens.

Empty when the render was abandoned, which fails closed at the next POST rather than handing out a token nothing can verify.

IPageSession

One visitor's key/value store, bounded and cleared when they sign out.

The handle is bound to the page that owns it, so a page writes, deletes and lists its own keys and cannot name another page's. Reading is deliberately open: a page may read another page's key by that page's path, which is what lets a page show what another page left for it. A value is addressed by (page, key); a bare key is not enough.

Every visitor gets a session of their own. It is minted when a page first writes and travels in an HttpOnly cookie the shell owns; a page that never writes costs a visitor nothing and gets no cookie. The session is cleared when the visitor signs out, and a session belonging to an account is only honoured for that account.

Values are JSON. Keys are ordinal and case-sensitive, 1 to the configured maximum characters, with no control characters. A write validates before it returns, and a read fails when its task is awaited: a key that is too long, a value that cannot be serialised as JSON, a value over its cap, a session over its key count or byte total, a write on a HEAD request, or a write to a session the shell has already discarded. A layout is offered the read and not the write.

The cap is per visitor, not per page: one page's keys can use the room another would have had. The idle lifetime is thirty minutes anonymously and eight hours when signed in.

MethodTryGetValueAsync<T>(string key)

Reads one of this page's values and reports whether the key exists.

Type parameters

T
The type to deserialise the stored JSON as.

Parameters

key
The key; ordinal, 1 to the configured maximum characters, no control characters.

Returns

Whether the key was found, and the value when it was. A missing key is not found with the default value. A stored JSON null is found with a null value, which is how a deliberately null value is told apart from an absent one. The test and the read are one operation, so they cannot race.

Exceptions

JsonException
The stored value does not deserialise as T.

MethodTryGetValueAsync<T>(string pagePath, string key)

Reads a value another page wrote.

Type parameters

T
The type to deserialise the stored JSON as.

Parameters

pagePath
The other page's path. It is normalised before use, so ../, a trailing slash and a different case all name the same page.
key
The key that page wrote.

Returns

Whether the key was found, and the value when it was.

Exceptions

ArgumentException
The path cannot name a page.
JsonException
The stored value does not deserialise as T.

MethodSetAsync<T>(string key, T value)

Stores one of this page's values, replacing any value already under the key.

Type parameters

T
The type to serialise.

Parameters

key
The key; ordinal, 1 to the configured maximum characters, no control characters.
value
The value; a null is stored as JSON null.

Returns

A task that completes when the write is committed.

Exceptions

ArgumentException
The key or the value breaks a cap.
InvalidOperationException
A layout or a HEAD render tried to write.

MethodDeleteAsync(string key)

Removes one of this page's keys.

Parameters

key
The key to remove.

Returns

Whether the key existed. Deleting a missing key is not an error.

Exceptions

InvalidOperationException
A layout or a HEAD render tried to write.

MethodKeysAsync()

Lists this page's keys.

Returns

The keys, in ordinal order.

MethodAllKeysAsync()

Lists every key this visitor's session holds, from every page.
A bare key cannot be read, so the pair is what is returned. This is bounded by the visitor's own cap and cannot reach another visitor.

Returns

The page and key pairs, ordered by page and then key.

IPageStorage

A page's own key/value store.

The handle is bound to the page that owns it, so a page can only reach its own keys. Every visitor shares that state, and a write is last-write-wins: a page that increments a counter is racy under concurrency.

A misuse is a page bug rather than a normal outcome, so it throws: a write validates before it returns, and a read fails when its task is awaited. A key that is too long, a value that cannot be serialised as JSON, a value over its cap, a page over its total cap, a write on a HEAD request, or a write to a page that was deleted while the render was running. The failure is detected before the row is written.

MethodTryGetValueAsync<T>(string key)

Reads a value and reports whether the key exists.

Type parameters

T
The type to deserialise the stored JSON as.

Parameters

key
The key; ordinal, 1 to Pages:Storage:MaxKeyChars characters, no control characters.

Returns

Whether the key was found, and the value when it was. A missing key is not found with the default value. A stored JSON null is found with a null value, which is how a deliberately null value is told apart from an absent one. The test and the read are one operation, so they cannot race.

Exceptions

JsonException
The stored value does not deserialise as T.

MethodSetAsync<T>(string key, T value)

Stores a value, replacing any value already under the key.

Type parameters

T
The type to serialise.

Parameters

key
The key; ordinal, 1 to Pages:Storage:MaxKeyChars characters, no control characters.
value
The value; a null is stored as JSON null.

Returns

A task that completes when the write is committed.

Exceptions

ArgumentException
The key or the value breaks a cap.

MethodDeleteAsync(string key)

Removes a key.

Parameters

key
The key to remove.

Returns

Whether the key existed. Deleting a missing key is not an error.

MethodKeysAsync()

Lists the page's keys.

Returns

The keys, in ordinal order.

IPageWrites

Writes the site's page store: this page's own source, and any page the visitor may edit.

The host offers this to every content layer and never to a layout, because a layout is markup and one that saved itself would append a revision on every page it wraps (`pages-layouts-are-markup`). The authority is the signed-in visitor's, not the page's. An anonymous render is refused with a UserFacingException before anything is compiled or stored; which page asked is not part of the check.

There are two saves. SaveAsync stores this page's own source, bound to Path, and answers PageSaveResult; it is a page repairing itself. SaveAsync stores any key the site's own routes do not answer, conditional on the head hash the form was rendered from, and answers PageEditResult. Both end in the same compile-then-store, so neither can answer differently about the same template. A restore, a seed install and a seed adopt are saves too: nothing is rewound, a tombstone comes back with its history, and one that would change nothing answers Unchanged.

A HEAD, an ended or timed-out render, a second write in one render, an unaddressable key and a reserved key are page bugs and throw InvalidOperationException; a key that names nothing is the page's own answer through Resolve, not an exception. The read members — Resolve and SeedSourceAsync — need no visitor and spend no action.

A write belongs to the next request: the running image is already loaded, so the response in hand is still the page as it was. A write that has begun is never abandoned — the render's deadline bounds the wait for a compile slot, not the author's edit — and one render makes one write, whichever member it uses (`pages-a-page-may-save-itself`).

MethodResolve(string key)

Normalises a key and reports whether the site's own routes answer for it.

Parameters

key
The text the page was given.

Returns

The canonical key, or why the text names no page.

MethodSeedSourceAsync(string key)

Reads the source this release ships for a seed.
A read, so it needs no signed-in visitor and is not the render's one action: a confirmation shows the diff between this and the live source, which is the one thing a page cannot read for itself. Reading it never grants a write — InstallSeedAsync decides that.

Parameters

key
The page's key; normalised before it is read.

Returns

The bundled source, or null when the release ships no seed for that key.

Exceptions

ArgumentException
The key cannot name a page.

MethodSaveAsync(string template)

Saves this page's own source as a new revision.
The bound save, for the page that repairs itself: one call, no key to get wrong, and the answer a page shows about itself. It is unconditional, so a page that wants the stale check names its own key through the other overload and passes its head hash.

Parameters

template
The template text. It may be empty; an empty page is a page.

Returns

The new revision's hash and the compiler's author-facing diagnostics.

Exceptions

ArgumentNullException
The template is null.
This render has no signed-in visitor, so nothing was saved.
InvalidOperationException
The request is a HEAD, the render was abandoned or its deadline passed before the save started, or this render has already written.

MethodSaveAsync(string key, string template, string expectedHash)

Saves a page, only while its head still has the expected revision.

Parameters

key
The page's key; normalised and checked.
template
The template text.
expectedHash
The head hash the form was rendered from, or null when the page had no live source: a new page, or a tombstone. A null expectation is refused as Stale if the page exists by the time the save runs, so a create cannot quietly overwrite one.

Exceptions

This render has no signed-in visitor, so nothing was saved.
InvalidOperationException
A reserved key, a HEAD, an ended render or a second write.

MethodAdoptSeedAsync(string key)

Records a seed as installed without storing a revision.
The answer to CanAdopt: the page already holds the bytes this release ships, so recording it as installed changes the record and nothing else. A page whose content no longer matches the seed is a page bug, and throws.

Parameters

key
The page's key; normalised and checked.

Returns

Null when the key is not a seed; the outcome is Unchanged when the record already names the shipped seed.

Exceptions

This render has no signed-in visitor.
InvalidOperationException
A reserved key, a HEAD, an ended render, a second write, or content that is not the seed.

MethodDeleteAsync(string key)

Tombstones a page, keeping its history.

Parameters

key
The page's key; normalised and checked.

Exceptions

This render has no signed-in visitor.
InvalidOperationException
A reserved key, a HEAD, an ended render or a second write.

MethodRestoreRevisionAsync(string key, string hash, string expectedHash)

Saves a retained revision's source as a new revision.

Parameters

key
The page's key; normalised and checked.
hash
The retained revision's hash, as the catalog reported it.
expectedHash
The live head the form was rendered from, or null for a tombstone.

Returns

Null when that page has no revision with that hash.

Exceptions

This render has no signed-in visitor.
InvalidOperationException
A reserved key, a HEAD, an ended render or a second write.

MethodInstallSeedAsync(string key, string expectedHash)

Saves a page the release ships with from its bundled source.

Parameters

key
The page's key; normalised and checked.
expectedHash
The live head the form was rendered from, or null for a tombstone.

Returns

Null when the key is not a seed.

Exceptions

This render has no signed-in visitor.
InvalidOperationException
A reserved key, a HEAD, an ended render or a second write.

IWorker

The entry point of a stored worker.
A worker is a stored source that declares exactly one public type implementing this interface, and that type is the whole program: a page starts one, and the host creates an instance and calls RunAsync once for the job. A worker renders nothing — it has no response, no layout and no session — so everything it has to say it says through its context.

MethodRunAsync(IWorkerContext context)

Runs the worker for one job.

Parameters

context
What this job is and what the worker may use while it runs.

Returns

A task that completes when the job is finished.

IWorkerContext

What a running worker is told about, and can do in, the job it is running.

It is deliberately not an IContext: a worker has no response to shape and no visitor waiting on it, so it is offered no way to write, flush, redirect or set a status. What it has is who it is running for, what it was sent, a way to ask for a capability, a way to wait for the next message and a way to publish what it has done.

A job is started by a signed-in visitor, so User is always the owner: a worker acts as that account for as long as the job runs. A worker that wants a connection, a store or the page catalog asks for it through Capabilities exactly as a page does; the host decides which are there, and a worker is offered no renderer, no writer and no layout.

PropertyId

This job's id, which the starting page used to start it.

PropertyPath

The canonical key of the page that started the job.

PropertyWorker

The canonical key of the worker source that is running.

PropertyUser

The visitor the job runs for.

PropertyInput

The first message the job was started with, or null when it had none.

PropertyAborted

Cancelled when the job must stop: a page asked, the host is stopping, or the job outran its silence or duration limit. A worker that ignores it is ended where it next awaits.

PropertyCapabilities

What this job offers, which is fewer things than a page's render does.

MethodLog(string message)

Writes to the job's log.

Parameters

message
The message.

MethodLogWarning(string message)

Writes a warning to the job's log.

Parameters

message
The message.

MethodLogError(string message)

Writes an error to the job's log.

Parameters

message
The message.

MethodReceiveAsync(double? waitSeconds)

Waits for the next message sent to this job.

Parameters

waitSeconds
How long to wait, capped by Pages:Jobs:MaxWaitSeconds. Omitted or null waits until a message arrives or the job ends.

Returns

The message, or null when the wait elapsed or the job can no longer receive — Aborted tells the two apart. A wait is not silence: it pauses the job's silence clock, so a worker waiting on its owner is bounded by the job's ceiling instead.

MethodPublish(string type, string dataJson)

Publishes one event to this job's journal.
A viewer reads it with ReadEventsAsync and waits for the next one; the journal keeps the most recent events and drops the oldest past its bounds, so an event is a progress report rather than a record. What must survive belongs in the starting page's storage.

Parameters

type
What the event is, such as delta or done.
dataJson
The event's text or JSON, bounded by Pages:Jobs:MaxEventBytes.

MarkdownOptions

The Markdown features a page may switch on or off for one render.

Options belong to the call, not to the capability: the renderer is shared, so a page that changed its settings would change every other page's. A page that wants a variant writes MarkdownOptions.Default with { HeadingAnchors = false } and passes it to ToHtml.

Raw HTML always passes through. It has no option because the page template can already write it, and a switch that looked like it turned HTML off would invite a page to trust the renderer with a visitor's text.

PropertyDefault

The page profile: heading anchors, auto-links and pipe tables all on.

PropertyHeadingAnchors

Whether each heading is written with an id derived from its text.
A repeated heading gets a numbered suffix, so a page can link to #heading and #heading-1. Turning this off writes a plain heading, for a page that supplies its own identifiers or holds several rendered fragments in one document.
Whether a bare URL becomes a link.

PropertyPipeTables

Whether a pipe table is rendered as a table.
One item in a navigation landmark.
A page builds these, so the two strings are checked where they enter the contract rather than where the document writer happens to notice.
One item in a navigation landmark.
A page builds these, so the two strings are checked where they enter the contract rather than where the document writer happens to notice.

Parameters

Href
The URL, unencoded: the document writer encodes it.
Text
The visible text, unencoded: the document writer encodes it.
IsCurrent
Whether this is the location being shown. A current item is text rather than a link to itself, marked so assistive technology says which one it is.
Whether this is the location being shown. A current item is text rather than a link to itself, marked so assistive technology says which one it is.
The URL, unencoded: the document writer encodes it.

Exceptions

ArgumentException
The URL is blank.
The visible text, unencoded: the document writer encodes it.

Exceptions

ArgumentException
The text is blank.

PageCapture

A rendered page's body beside the frame it contributes.

A page rendered inside another page yields this value: its whole body, wrappers and all, plus the title, head, sheets and script permission of the outermost layer. A wrapper receives the layer inside it as Content, and a page that does not want to be wrapped can ask for the same value with CaptureAsync.

It is a value, not a capability: the captured page's response stays withheld, so its status, headers and content type never reach the caller. A page that would have redirected refuses instead, because a capture has no response to redirect.

MethodPageCapture(string body, PageFrame frame)

Pairs a body with the frame of the layer that wrote it.

Parameters

body
The outermost layer's body.
frame
The outermost layer's frame.

Exceptions

ArgumentNullException
The body or the frame is null.

PropertyBody

The outermost layer's body.

PageDeleteResult

What a delete answered with.

MethodPageDeleteResult(bool Deleted, bool WasLive)

What a delete answered with.

Parameters

Deleted
Whether this call tombstoned the page; a missing page answers false rather than failing.
WasLive
Whether the page was live before the call.

PropertyDeleted

Whether this call tombstoned the page; a missing page answers false rather than failing.

PropertyWasLive

Whether the page was live before the call.

PageDiagnostic

One problem a save found in the template, ready for the author to read.

This is the page's copy of the compiler's diagnostic: severity, a position in the template the author typed, the code the logs and the editor quote, and the text. Core.Compilation keeps its own PageDiagnostic, because moving it here would make the generator depend on the page contract; the page's save maps between them (`pages-a-page-may-save-itself`).

A position is 1-based template space, and an unknown position is both members null rather than 0, so it cannot be mistaken for a real one.

MethodPageDiagnostic(PageDiagnosticSeverity Severity, int? Line, int? Column, string Code, string Message)

One problem a save found in the template, ready for the author to read.

This is the page's copy of the compiler's diagnostic: severity, a position in the template the author typed, the code the logs and the editor quote, and the text. Core.Compilation keeps its own PageDiagnostic, because moving it here would make the generator depend on the page contract; the page's save maps between them (`pages-a-page-may-save-itself`).

A position is 1-based template space, and an unknown position is both members null rather than 0, so it cannot be mistaken for a real one.

Parameters

Severity
Whether the page can still be served.
Line
The 1-based line in the template, or null when it is not known.
Column
The 1-based column in the template, or null when it is not known.
Code
The author-facing code — PAGE001, TEMPLATE002, CS1002 — or empty when the message carries none.
Message
The text of the diagnostic, without its code, position or severity.

PropertySeverity

Whether the page can still be served.

PropertyLine

The 1-based line in the template, or null when it is not known.

PropertyColumn

The 1-based column in the template, or null when it is not known.

PropertyCode

The author-facing code — PAGE001, TEMPLATE002, CS1002 — or empty when the message carries none.

PropertyMessage

The text of the diagnostic, without its code, position or severity.

PageDiagnosticSeverity

How serious a PageDiagnostic is.

FieldWarning

The page compiles and is served; the warning is unfinished work.

FieldError

The page is stored but produces no image, so it cannot be served until it is fixed.

PageEditOutcome

What happened to an edit.

FieldSaved

The source was stored as a new revision.

FieldStale

The head moved since the form was rendered, so nothing was written.

FieldUnchanged

The page already held the source, so nothing was written.

PageEditResult

What an edit answered with.
A save with errors is still stored — the author's edit is never lost — so the diagnostics are how the page says what to fix, and HasErrors says whether the next request can serve it.

MethodPageEditResult(PageEditOutcome Outcome, string Hash, IReadOnlyList<PageDiagnostic> Diagnostics)

What an edit answered with.
A save with errors is still stored — the author's edit is never lost — so the diagnostics are how the page says what to fix, and HasErrors says whether the next request can serve it.

Parameters

Outcome
Whether the source was stored, refused as stale, or already current.
Hash
The revision's hash when something was stored or already current; otherwise null.
Diagnostics
The compiler's author-facing answer, ordered by template position.

PropertyOutcome

Whether the source was stored, refused as stale, or already current.

PropertyHash

The revision's hash when something was stored or already current; otherwise null.

PropertyDiagnostics

The compiler's author-facing answer, ordered by template position.

PropertyHasErrors

Whether the save found an error, which leaves the page unservable until it is fixed.

PropertyHasWarnings

Whether the save found a warning, which does not stop the page being served.

PageEntry

One row of a page listing: a key, its head's revision and what kind of key it is.

The marks are the host's own rules reported rather than derived: a view can filter a listing without owning the reserved-path list, the content-type table or the revision verdict.

State is what the head's image compiled to, in the host's words — "Compiled", "Compiled with warnings", "Compile failed", "Stale", "Not compiled" or "Stored as source" — so a page's listing says exactly what the shell's own listing says, without reading source or inventing a second spelling. How a view marks it is the view's business: the shell's list has a class of its own, and a page may use the words as an attribute or map them to its own class.

MethodPageEntry(string Key, DateTimeOffset SavedAt, string Hash, bool IsDeleted, bool IsReserved, bool IsHtml)

One row of a page listing: a key, its head's revision and what kind of key it is.

The marks are the host's own rules reported rather than derived: a view can filter a listing without owning the reserved-path list, the content-type table or the revision verdict.

State is what the head's image compiled to, in the host's words — "Compiled", "Compiled with warnings", "Compile failed", "Stale", "Not compiled" or "Stored as source" — so a page's listing says exactly what the shell's own listing says, without reading source or inventing a second spelling. How a view marks it is the view's business: the shell's list has a class of its own, and a page may use the words as an attribute or map them to its own class.

Parameters

Key
The page's canonical key.
SavedAt
When the head's revision was saved.
Hash
The head's revision hash.
IsDeleted
Whether the page is a tombstone, which retains its history.
IsReserved
Whether the site's own routes already answer for the key.
IsHtml
Whether the key is served as HTML.

PropertyKey

The page's canonical key.

PropertySavedAt

When the head's revision was saved.

PropertyHash

The head's revision hash.

PropertyIsDeleted

Whether the page is a tombstone, which retains its history.

PropertyIsReserved

Whether the site's own routes already answer for the key.

PropertyIsHtml

Whether the key is served as HTML.

PropertyIsAsset

Whether the head has no code, so its source is the response.

PropertyIsLibrary

Whether the head is a library: declarations only, compiled into the pages that name it and never served.

PropertyIsWorker

Whether the head is a worker: declarations that program a job a page starts, and never served.

PropertyState

What the head's image compiled to, in the host's words.

PropertySeed

What this page is relative to the seed the release ships, or null when the key has no seed either side of the store.

PageFrame

What a rendered page contributes outside its body.

This is the finished material of one layer, not the live IPageLayout a layer runs with: it can be carried, folded into the caller's own slots, or discarded. A page that embeds another page receives this from EmbedAsync, where the body is already written; a wrapper receives the layer inside it as a PageCapture.

Nothing is merged behind the outer page's back. The page that owns the document decides what to fold, with AddHead and AddStylesheet on its own slots, so an abstract frame and an abstract body are all a composition ever hands over.

MethodPageFrame(string Title, string Head, IReadOnlyList<string> Stylesheets, bool AllowsScripts)

What a rendered page contributes outside its body.

This is the finished material of one layer, not the live IPageLayout a layer runs with: it can be carried, folded into the caller's own slots, or discarded. A page that embeds another page receives this from EmbedAsync, where the body is already written; a wrapper receives the layer inside it as a PageCapture.

Nothing is merged behind the outer page's back. The page that owns the document decides what to fold, with AddHead and AddStylesheet on its own slots, so an abstract frame and an abstract body are all a composition ever hands over.

Parameters

Title
The outermost layer's title, or null when it set none.
Head
The outermost layer's AddHead markup.
Stylesheets
The outermost layer's sheets, in the order it added them.
AllowsScripts
Whether the page, or any layer it is wrapped in, asked to load same-origin scripts.

PropertyTitle

The outermost layer's title, or null when it set none.

PropertyHead

The outermost layer's AddHead markup.

PropertyStylesheets

The outermost layer's sheets, in the order it added them.

PropertyAllowsScripts

Whether the page, or any layer it is wrapped in, asked to load same-origin scripts.

PageJobEvent

One thing a running worker published.

MethodPageJobEvent(long Sequence, string Type, string Data)

One thing a running worker published.

Parameters

Sequence
The event's position in this job's journal, counting from one. A viewer passes the last sequence it saw back to ReadEventsAsync; the gap between them is never wider than the journal, and a viewer whose position has been dropped is told so.
Type
The name the worker gave the event, such as delta or done.
Data
The event's text or JSON, exactly as the worker published it.

PropertySequence

The event's position in this job's journal, counting from one. A viewer passes the last sequence it saw back to ReadEventsAsync; the gap between them is never wider than the journal, and a viewer whose position has been dropped is told so.

PropertyType

The name the worker gave the event, such as delta or done.

PropertyData

The event's text or JSON, exactly as the worker published it.

PageJobEvents

What one read of a job's journal answered.

MethodPageJobEvents(IReadOnlyList<PageJobEvent> Events, long Next, bool Reset, PageJobState? State, string Failure)

What one read of a job's journal answered.

Parameters

Events
The events after the caller's sequence, oldest first; empty when there are none.
Next
The sequence to pass back next: the last event's, or the caller's own when nothing arrived. A reset moves it to the oldest sequence the journal still holds.
Reset
Whether the caller's sequence had already been dropped. The view should start again from Next rather than treat what it missed as delivered.
State
The job's state when the call answered, or null when it is gone.
Failure
Why the job failed, or null when it did not.

PropertyEvents

The events after the caller's sequence, oldest first; empty when there are none.

PropertyNext

The sequence to pass back next: the last event's, or the caller's own when nothing arrived. A reset moves it to the oldest sequence the journal still holds.

PropertyReset

Whether the caller's sequence had already been dropped. The view should start again from Next rather than treat what it missed as delivered.

PropertyState

The job's state when the call answered, or null when it is gone.

PropertyFailure

Why the job failed, or null when it did not.

PageJobInfo

One job as its owner sees it.

MethodPageJobInfo(string Id, string Worker, string Path, PageJobState State, DateTimeOffset StartedAt, DateTimeOffset? EndedAt, string Failure)

One job as its owner sees it.

Parameters

Id
The job's id.
Worker
The canonical key of the worker that is running.
Path
The canonical key of the page that started it.
State
What the job is doing, or how it ended.
StartedAt
When it was accepted.
EndedAt
When it finished, or null while it is still running.
Failure
Why it failed, in the host's words, or null when it did not. A job starts with a null and only a failure sets it.

PropertyId

The job's id.

PropertyWorker

The canonical key of the worker that is running.

PropertyPath

The canonical key of the page that started it.

PropertyState

What the job is doing, or how it ended.

PropertyStartedAt

When it was accepted.

PropertyEndedAt

When it finished, or null while it is still running.

PropertyFailure

Why it failed, in the host's words, or null when it did not. A job starts with a null and only a failure sets it.

PageJobRefusal

Why a job call was refused, as a value a page can branch on.

FieldNone

Nothing was refused.

FieldAnonymous

The render is not signed in, and a job belongs to an account.

FieldReadOnly

The render is a HEAD, which reads and never writes.

FieldInvalidKey

The key is not an addressable page key.

FieldOwnedBySite

The site's own routes answer the key, so no worker is stored there.

FieldUnknownWorker

No page is stored at the key.

FieldNotAWorker

The key holds a page, a text asset or a library rather than a worker.

FieldQueueFull

Every slot in the job queue is taken.

FieldUnknownJob

No job with that id belongs to this visitor.

FieldEnded

The job has already finished, so it cannot receive.

FieldTooManyMessages

The job's pending messages are at their limit.

FieldMessageTooLarge

The message is larger than Pages:Jobs:MaxMessageBytes.

PageJobSendResult

The answer to a message sent to a job.

MethodPageJobSendResult(PageJobRefusal Refusal)

The answer to a message sent to a job.

Parameters

Refusal
Why it was refused, or None.

PropertyRefusal

Why it was refused, or None.

PropertySent

Whether the message was queued for the worker.

PageJobStart

The answer to a job that was asked to start.

MethodPageJobStart(string Id, PageJobRefusal Refusal)

The answer to a job that was asked to start.

Parameters

Id
The new job's id, or null when it was refused.
Refusal
Why it was refused, or None.

PropertyId

The new job's id, or null when it was refused.

PropertyRefusal

Why it was refused, or None.

PropertyStarted

Whether the job started.

PageJobState

What a job is doing, or how it ended.

FieldQueued

Accepted, and waiting for a runner.

FieldRunning

The worker is running.

FieldCompleted

The worker returned.

FieldFailed

The worker threw, or its image could not be loaded.

FieldCancelled

A page asked it to stop, or the host did.

PageKeyResolution

What a key names, as Resolve reports it.
A page's edited key arrives as a query value, so a key that names nothing is an answer the page renders rather than an exception it catches. IsReserved is the host's own routing rule reported, so the page can explain why a shell file is not editable without owning the list.

MethodPageKeyResolution(string Key, bool IsReserved, string Error)

What a key names, as Resolve reports it.
A page's edited key arrives as a query value, so a key that names nothing is an answer the page renders rather than an exception it catches. IsReserved is the host's own routing rule reported, so the page can explain why a shell file is not editable without owning the list.

Parameters

Key
The canonical key, or null when the text names no page.
IsReserved
Whether one of the site's own routes answers for the key.
Error
Why the text names no page, or null when it does.

PropertyKey

The canonical key, or null when the text names no page.

PropertyIsReserved

Whether one of the site's own routes answers for the key.

PropertyError

Why the text names no page, or null when it does.

PropertyIsSuccess

Whether the text names a page.

PageRequest

The request a page runs against, as plain values.

A snapshot taken before the handler runs, so a page cannot observe the request changing under it and the runtime never needs to hand page code an ASP.NET type.

Query, Form and Headers hold one value per name: a repeated field keeps its first value, which is the common case and the name a page already knows. QueryValues and FormValues hold every value in the order the request sent them, for a multi-select or ?tag=a&tag=b.

MethodPageRequest(string Method, string Path, IReadOnlyDictionary<string, string> Query, IReadOnlyDictionary<string, string> Form, IReadOnlyDictionary<string, string> Headers, IReadOnlyDictionary<string, string> Cookies, IReadOnlyDictionary<string, IReadOnlyList<string>> QueryValues, IReadOnlyDictionary<string, IReadOnlyList<string>> FormValues)

The request a page runs against, as plain values.

A snapshot taken before the handler runs, so a page cannot observe the request changing under it and the runtime never needs to hand page code an ASP.NET type.

Query, Form and Headers hold one value per name: a repeated field keeps its first value, which is the common case and the name a page already knows. QueryValues and FormValues hold every value in the order the request sent them, for a multi-select or ?tag=a&tag=b.

Parameters

Method
The HTTP method, for example GET or POST.
Path
The canonical page key, which always starts with /.
Query
The query string, collapsed to one value per name.
Form
The submitted form, collapsed to one value per name, or empty when the request is not a form post.
Headers
The request headers, collapsed to one value per name.
Cookies
The request cookies.
QueryValues
Every query value per name, in the order the request sent them.
FormValues
Every form value per name, in the order sent, or empty when the request is not a form post.

PropertyMethod

The HTTP method, for example GET or POST.

PropertyPath

The canonical page key, which always starts with /.

PropertyQuery

The query string, collapsed to one value per name.

PropertyForm

The submitted form, collapsed to one value per name, or empty when the request is not a form post.

PropertyHeaders

The request headers, collapsed to one value per name.

PropertyCookies

The request cookies.

PropertyQueryValues

Every query value per name, in the order the request sent them.

PropertyFormValues

Every form value per name, in the order sent, or empty when the request is not a form post.

PageRequestExtensions

Copies of a PageRequest with a changed query.

A composed page runs against a request, so the request is the page's input. These are the copy-and-change helpers: the record keeps its shape and its own surface stays the values it carries, while a caller shapes the query an embed or a wrapper sees without building a second type for it.

Query and QueryValues are rebuilt together, so the two views of the same query cannot disagree. The order the names were added in is kept, and a repeated name keeps the order of its values.

MethodWithQuery(PageRequest request, string name, string value)

Replaces every value of one query name with a single value.

Parameters

request
The request to copy.
name
The query name.
value
The value to give it; it may not be null.

Returns

A copy with the name's values replaced, in the position the name already had.

Exceptions

ArgumentNullException
request or value is null.
ArgumentException
name is blank.

MethodWithQuery(PageRequest request, IReadOnlyList<KeyValuePair<string, string>> query)

Replaces the whole query with the pairs given.

Parameters

request
The request to copy.
query
The query, in the order the caller wants it, repeated names included.

Returns

A copy whose query is exactly query.

Exceptions

ArgumentNullException
request or query is null.
ArgumentException
A name is blank, or a value is null.

MethodWithAnotherQuery(PageRequest request, string name, string value)

Adds a value beside the ones the query name already has.

Parameters

request
The request to copy.
name
The query name.
value
The value to add; it may not be null.

Returns

A copy with the value added after the name's existing values.

Exceptions

ArgumentNullException
request or value is null.
ArgumentException
name is blank.

MethodWithoutQuery(PageRequest request, string name)

Drops one query name and every value it carried.

Parameters

request
The request to copy.
name
The query name to drop.

Returns

A copy without the name.

Exceptions

ArgumentNullException
request is null.
ArgumentException
name is blank.

MethodWithoutQuery(PageRequest request)

Drops the whole query.

Parameters

request
The request to copy.

Returns

A copy with no query.

Exceptions

ArgumentNullException
request is null.

PageResponse

What a page asked the response to be.
The shell applies this after the handler has returned, which is why the body is buffered: a page that throws contributes no status, no headers and no output. A page that calls FlushAsync applies it at the first flush instead, and the response is final from then on.

MethodPageResponse(int Status, string ContentType, IReadOnlyDictionary<string, string> Headers, string Location)

What a page asked the response to be.
The shell applies this after the handler has returned, which is why the body is buffered: a page that throws contributes no status, no headers and no output. A page that calls FlushAsync applies it at the first flush instead, and the response is final from then on.

Parameters

Status
The status code, normally 200.
ContentType
The content type, normally text/html; charset=utf-8.
Headers
The extra response headers the page set.
Location
The redirect target, or null when the page did not redirect.

PropertyStatus

The status code, normally 200.

PropertyContentType

The content type, normally text/html; charset=utf-8.

PropertyHeaders

The extra response headers the page set.

PropertyLocation

The redirect target, or null when the page did not redirect.

PropertyAllowsScripts

Whether the page asked to load same-origin scripts.
The shell turns this into script-src 'self' on the response's Content-Security-Policy; inline scripts stay blocked either way.

PropertyDefault

The response a page gets when it asks for nothing in particular.

PageResponseDeprecation

The one message every member the page contract has replaced carries.
It is internal so it is not itself part of the API a page binds against, and it is one constant so the members that carry it cannot drift apart.

FieldDeprecated

What a page should say instead of the replaced member.

PageRevisionInfo

One row of a page's history.

MethodPageRevisionInfo(string Hash, DateTimeOffset SavedAt, bool IsCurrent)

One row of a page's history.

Parameters

Hash
The revision's hash, which ReadRevisionAsync takes.
SavedAt
When the revision was saved.
IsCurrent
Whether the page's live head points at this revision. Always false for a tombstoned page, which has no live head.

PropertyHash

The revision's hash, which ReadRevisionAsync takes.

PropertySavedAt

When the revision was saved.

PropertyIsCurrent

Whether the page's live head points at this revision. Always false for a tombstoned page, which has no live head.

PageSaveResult

What a save of a page's own source answered with.
The answer a page needs to render its own reply: the revision it became, and whether that compiled clean, with warnings, or with errors. A save with errors is still stored — the author's edit is never lost — so the diagnostics are how the page says what to fix, and HasErrors says whether the next request can serve it at all.

MethodPageSaveResult(string Hash, IReadOnlyList<PageDiagnostic> Diagnostics)

What a save of a page's own source answered with.
The answer a page needs to render its own reply: the revision it became, and whether that compiled clean, with warnings, or with errors. A save with errors is still stored — the author's edit is never lost — so the diagnostics are how the page says what to fix, and HasErrors says whether the next request can serve it at all.

Parameters

Hash
The new revision's hash, as RevisionsAsync reports it.
Diagnostics
The compiler's author-facing answer, ordered by template position.

PropertyHash

The new revision's hash, as RevisionsAsync reports it.

PropertyDiagnostics

The compiler's author-facing answer, ordered by template position.

PropertyHasErrors

Whether the save found an error, which leaves the page unservable until it is fixed.

PropertyHasWarnings

Whether the save found a warning, which does not stop the page being served.

PageSeedSummary

What a listing says about a page's relation to the seed this release ships.
The marks are the host's rules reported rather than derived, exactly as State is: a page renders the sentence and offers the actions the flags permit, and it never compares a hash or decides whether a write is safe. The verdict is a string because this assembly references nothing, the core's comparison included.

MethodPageSeedSummary(string Verdict, string Sentence, bool CanApply, bool CanAdopt)

What a listing says about a page's relation to the seed this release ships.
The marks are the host's rules reported rather than derived, exactly as State is: a page renders the sentence and offers the actions the flags permit, and it never compares a hash or decides whether a write is safe. The verdict is a string because this assembly references nothing, the core's comparison included.

Parameters

Verdict
The verdict in the host's words — "in sync", "release newer", "edited", "conflict", "store newer", "unknown", "retired", "new" or "deleted".
Sentence
One sentence the page can show beside the row, in the host's words.
CanApply
Whether the host will let this row be replaced with the shipped seed.
CanAdopt
Whether the host will record the shipped seed as installed without changing the content.

PropertyVerdict

The verdict in the host's words — "in sync", "release newer", "edited", "conflict", "store newer", "unknown", "retired", "new" or "deleted".

PropertySentence

One sentence the page can show beside the row, in the host's words.

PropertyCanApply

Whether the host will let this row be replaced with the shipped seed.

PropertyCanAdopt

Whether the host will record the shipped seed as installed without changing the content.

PageSessionKey

One key of one page's per-visitor session state.
A session value is addressed by the page that wrote it and the key that page chose. A bare key cannot be read because two pages may use the same key for different things.

MethodPageSessionKey(string Page, string Key)

One key of one page's per-visitor session state.
A session value is addressed by the page that wrote it and the key that page chose. A bare key cannot be read because two pages may use the same key for different things.

Parameters

Page
The canonical page key the value belongs to.
Key
The key that page chose.

PropertyPage

The canonical page key the value belongs to.

PropertyKey

The key that page chose.

PageSource

A page's template, with the revision it belongs to.
The source is text, not markup: write it with Write so it is escaped, because a template is exactly the kind of value a source view must not run.

MethodPageSource(string Key, string Hash, DateTimeOffset SavedAt, string Source)

A page's template, with the revision it belongs to.
The source is text, not markup: write it with Write so it is escaped, because a template is exactly the kind of value a source view must not run.

Parameters

Key
The page's canonical key.
Hash
The revision's hash.
SavedAt
When the revision was saved.
Source
The template text, exactly as it was stored.

PropertyKey

The page's canonical key.

PropertyHash

The revision's hash.

PropertySavedAt

When the revision was saved.

PropertySource

The template text, exactly as it was stored.

PageStreamRefusedException

Thrown when the host cannot start a stream because every stream slot is taken.

The throw happens before the response is committed, so the page can still set a status, a content type and a body, and the shell answers 503 Service Unavailable when the page does not catch it. A page that would rather explain the wait itself catches this and renders an ordinary document.

It derives from InvalidOperationException because that is the exception FlushAsync documents, so a page written against the old contract still catches it.

MethodPageStreamRefusedException(string)

Thrown when the host cannot start a stream because every stream slot is taken.

The throw happens before the response is committed, so the page can still set a status, a content type and a body, and the shell answers 503 Service Unavailable when the page does not catch it. A page that would rather explain the wait itself catches this and renders an ordinary document.

It derives from InvalidOperationException because that is the exception FlushAsync documents, so a page written against the old contract still catches it.

PageUser

The local account a page is running for, as a plain value.
Deliberately smaller than the host's own account record: a page learns who is signed in, not the password hash, the security stamp or the row. Only User creates one, so a page cannot construct an identity the shell will believe.

MethodPageUser(string Name)

The local account a page is running for, as a plain value.
Deliberately smaller than the host's own account record: a page learns who is signed in, not the password hash, the security stamp or the row. Only User creates one, so a page cannot construct an identity the shell will believe.

Parameters

Name
The normalised user name from the sign-in cookie.

PropertyName

The normalised user name from the sign-in cookie.

PageValue<T>

Whether a stored key was found, and the value read when it was.
An out parameter cannot be used on the asynchronous storage read, so presence and value travel together instead. A stored JSON null is found with a null value; an absent key is not found with the default.

Type parameters

T
The type the value was deserialised as.

MethodPageValue(bool Found, T Value)

Whether a stored key was found, and the value read when it was.
An out parameter cannot be used on the asynchronous storage read, so presence and value travel together instead. A stored JSON null is found with a null value; an absent key is not found with the default.

Type parameters

T
The type the value was deserialised as.

Parameters

Found
Whether the key exists.
Value
The stored value, or the default when the key is absent.

PropertyFound

Whether the key exists.

PropertyValue

The stored value, or the default when the key is absent.

ShellAudience

Who a shell link is for.
A page filters on this with its own User, so a menu a page draws agrees with the guard on the page it links to.

FieldEveryone

Every visitor, signed in or not.

FieldAnonymous

A visitor who has not signed in.

FieldOwner

A signed-in visitor, which on this site is the owner.
One link the shell knows how to draw, as a value rather than as markup.

ShellLinks returns these, and the page filters, orders, labels and marks them itself: there is no current flag and no rendered menu, because the page owns its markup. A page may also build one of its own beside the host's.

The two strings are checked where they enter the contract rather than where a document writer happens to notice, as NavLink does.

MethodShellLink(string Href, string Text, ShellSection Section, ShellAudience Audience, ShellMatch Match)

One link the shell knows how to draw, as a value rather than as markup.

ShellLinks returns these, and the page filters, orders, labels and marks them itself: there is no current flag and no rendered menu, because the page owns its markup. A page may also build one of its own beside the host's.

The two strings are checked where they enter the contract rather than where a document writer happens to notice, as NavLink does.

Parameters

Href
The URL, unencoded: the document writer encodes it.
Text
The visible text, unencoded: the document writer encodes it.
Section
Which of the shell's menus it belongs to.
Audience
Who it is for.
Match
How a request path marks it current. A page may ignore it; a page that follows it draws the same current item the shell's own menus do.

PropertySection

Which of the shell's menus it belongs to.

PropertyAudience

Who it is for.

PropertyMatch

How a request path marks it current. A page may ignore it; a page that follows it draws the same current item the shell's own menus do.

PropertyHref

The URL, unencoded: the document writer encodes it.

Exceptions

ArgumentException
The URL is blank.

PropertyText

The visible text, unencoded: the document writer encodes it.

Exceptions

ArgumentException
The text is blank.

ShellMatch

How a request path marks a shell link as the place being shown.
It is a fact about the route, not a rendering rule: a page may mark its menu however it likes, and using this keeps a page's menu agreeing with the shell's own.

FieldLeaf

The path is the link's own, and nothing beneath it.

FieldSubtree

The path is the link's own, or a page or route beneath it.

ShellSection

Which of the shell's menus a link belongs to.

FieldSite

The site menu every document carries.

FieldAdministration

The administration menu, and the index it belongs to.

UserFacingException

An exception whose message is safe to show to the user.
This is the only signal the shell trusts for display: every other exception is reported with a generic message, because its text routinely contains paths, connection strings or page source. The runtime unwraps the reflection wrapper around a page's exception, so a page that throws one of these loses neither its message nor its stack.

MethodUserFacingException(string message)

Creates an exception with a message approved for display to the user.

Parameters

message
The user-safe message.