The page contract
uk.osric.asp.Sdk
HttpFetchFailure
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
FieldInvalidRequest
FieldTimeout
FieldAborted
FieldNetwork
FieldHttpError
FieldTooManyRequests
FieldTooManyRedirects
HttpFetchMethod
FieldGet
FieldPost
HttpFetchRequest
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)
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
httporhttpsURL, with no credentials and no fragment.
PropertyUrl
http or https URL, with no credentials and no fragment.Exceptions
ArgumentException- The URL is blank.
PropertyMethod
PropertyBody
POST only, and text only.PropertyHeaders
X- name, and no line breaks.
PropertyCredential
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
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)
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
0when 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
0 when no response was received.PropertyHeaders
X- name.PropertyBody
PropertyFailure
PropertyTruncated
PropertySucceeded
HttpFetchStream
MethodHttpFetchStream()
PropertyStatus
PropertyHeaders
PropertyFailure
PropertyTruncated
MethodReadLineAsync()
null when the stream has ended.Returns
null at end of stream.MethodCloseAsync()
Returns
IBuildInfo
null rather than a placeholder a page might mistake for a hash.
PropertyCommit
null when the build has none.IContext
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
PropertyPath
PropertyEditorPath
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
null for an anonymous visitor.if (ctx.User is not { } user) { ctx.Response.RedirectToLogin(); return; }.
PropertyAborted
PropertyResponse
MethodLog(string message)
Parameters
message- The message to log.
MethodLogWarning(string message)
Parameters
message- The message to log.
MethodLogError(string message)
Parameters
message- The message to log.
MethodAssetUrl(string href)
Parameters
href- The link as the page would write it.
Returns
?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
null; a page decides whether
that is fatal with Get<T> or
GetRequired<T>.
MethodWriteRaw(string message)
Parameters
message- The HTML to write.
MethodWrite(string message)
Parameters
message- The text to escape and write.
MethodFlushAsync()
Returns
MethodSetStatus(int status)
Parameters
status- The code to send, between 100 and 599.
MethodSetContentType(string contentType)
Parameters
contentType- The media type to send.
MethodSetHeader(string name, string value)
Parameters
name- The header name.
value- The header value; it may not contain a line break.
MethodAllowScripts()
MethodRedirect(string location, int status)
Parameters
location- The target, relative or absolute.
status- The redirect status; 302 by default.
MethodRedirectToLogin()
PropertyAntiforgeryField
IDiffRenderer
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)
Parameters
before- The earlier document.
after- The later document.
Returns
<%== %>.Exceptions
ArgumentNullException- Either document is
null.
IHandler
MethodHandleAsync(IContext context)
Parameters
context- The context the page reads and writes through.
Returns
IHttpFetch
MethodSendAsync(HttpFetchRequest request)
Parameters
request- The request to make.
Returns
MethodStreamAsync(HttpFetchRequest request)
Parameters
request- The request to make.
Returns
MethodGetAsync(string url)
GET request.Parameters
url- An absolute
httporhttpsURL.
Returns
MethodPostAsync(string url, string body)
POST request with a text body.Parameters
url- An absolute
httporhttpsURL. body- The text body; the host sends it as
text/plainunless a header says otherwise.
Returns
IMarkdownRenderer
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)
Parameters
markdown- The Markdown to render. Raw HTML in it is passed through.
Returns
<%== %>.Exceptions
ArgumentNullExceptionmarkdownisnull.
MethodToHtml(string markdown, MarkdownOptions options)
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
<%== %>.Exceptions
ArgumentNullException-
markdownoroptionsisnull.
IPageCapabilities
null.
MethodTryGet<T>(ref T capability)
Parameters
capability- The implementation, when this render offers the capability.
Returns
MethodGet<T>()
null when this render does not offer it.MethodGetRequired<T>()
Exceptions
InvalidOperationException- This render does not offer the capability.
IPageCatalog
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.
MethodShellLinks()
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
Exceptions
InvalidOperationException- The render was abandoned.
MethodListAsync(string prefix)
Parameters
prefix-
The subtree to list.
""and"/"are the whole store; any other value is normalised as a page key, so/Blog/and/blogare the same request. A prefix lists the key itself and the keys beneath it, never a key that merely starts with the same text:/bloglists/blogand/blog/post, never/blogroll.
Returns
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)
Parameters
key- The page's key; normalised before it is read.
Returns
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)
Parameters
key- The page's key; normalised before it is read.
Returns
Exceptions
ArgumentException- The key cannot name a page.
InvalidOperationException- The render was abandoned.
MethodReadRevisionAsync(string key, string hash)
Parameters
key- The page's key; normalised before it is read.
hash- The revision's hash, as RevisionsAsync reported it.
Returns
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
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)
Parameters
key- The embedded page's canonical key, such as
/cards/post. request- The request to run it against, or
nullfor this page's.
Returns
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)
Parameters
key- The captured page's canonical key.
request- The request to run it against, or
nullfor this page's.
Returns
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)
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
nullfor 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()
Exceptions
InvalidOperationException- The response has already been flushed.
IPageJobs
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)
workerKey.Parameters
workerKey- The canonical key of a stored worker.
firstMessage-
The first message the worker receives, or
nullwhen it needs none. Bounded byPages:Jobs:MaxMessageBytes.
Returns
MethodSendAsync(string jobId, string message)
Parameters
jobId- The id a start or a listing answered with.
message- The message text or JSON, bounded by
Pages:Jobs:MaxMessageBytes.
Returns
MethodGetAsync(string jobId)
Parameters
jobId- The id a start or a listing answered with.
Returns
null when it is unknown or another visitor's.MethodListAsync()
Returns
MethodReadEventsAsync(string jobId, long after, double? waitSeconds)
Parameters
jobId- The id a start or a listing answered with.
after- The last sequence the caller has already seen;
0reads from the start. waitSeconds-
How long to wait for an event that has not arrived yet, capped by
Pages:Jobs:MaxWaitSecondsand by the render's own budget. Omitted ornulldoes not wait.
Returns
after, or a reset when the journal no longer holds that
sequence, with the job's state once it has ended.
MethodCancelAsync(string jobId)
Parameters
jobId- The id a start or a listing answered with.
Returns
IPageLayout
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
null otherwise.PropertyTitle
null until it is set.Exceptions
ArgumentException- The title is blank.
PropertyHead
PropertyStylesheets
MethodAddHead(string markup)
head.Parameters
markup- The markup to add; it is the caller's, not a request value.
MethodAddStylesheet(string href)
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
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)
Parameters
message- The HTML to write.
MethodWrite(string message)
Parameters
message- The text to escape and write.
MethodFlushAsync()
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
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
503unless the page catches this and writes its own document.
MethodSetStatus(int status)
Parameters
status- The code to send, between 100 and 599.
MethodSetContentType(string contentType)
Parameters
contentType- The media type to send.
MethodSetHeader(string name, string value)
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()
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)
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=metricsarrives as written. status- The redirect status; 302 by default.
MethodRedirectToLogin()
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
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
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)
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
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)
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
Exceptions
ArgumentException- The path cannot name a page.
JsonException- The stored value does not deserialise as
T.
MethodSetAsync<T>(string key, T value)
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
Exceptions
ArgumentException- The key or the value breaks a cap.
InvalidOperationException- A layout or a
HEADrender tried to write.
MethodDeleteAsync(string key)
Parameters
key- The key to remove.
Returns
Exceptions
InvalidOperationException- A layout or a
HEADrender tried to write.
MethodKeysAsync()
Returns
MethodAllKeysAsync()
Returns
IPageStorage
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)
Type parameters
T- The type to deserialise the stored JSON as.
Parameters
key- The key; ordinal, 1 to
Pages:Storage:MaxKeyCharscharacters, no control characters.
Returns
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)
Type parameters
T- The type to serialise.
Parameters
key- The key; ordinal, 1 to
Pages:Storage:MaxKeyCharscharacters, no control characters. value- The value; a null is stored as JSON
null.
Returns
Exceptions
ArgumentException- The key or the value breaks a cap.
MethodDeleteAsync(string key)
Parameters
key- The key to remove.
Returns
MethodKeysAsync()
Returns
IPageWrites
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)
Parameters
key- The text the page was given.
Returns
MethodSeedSourceAsync(string key)
Parameters
key- The page's key; normalised before it is read.
Returns
null when the release ships no seed for that key.Exceptions
ArgumentException- The key cannot name a page.
MethodSaveAsync(string template)
Parameters
template- The template text. It may be empty; an empty page is a page.
Returns
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)
Parameters
key- The page's key; normalised and checked.
template- The template text.
expectedHash-
The head hash the form was rendered from, or
nullwhen 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)
Parameters
key- The page's key; normalised and checked.
Returns
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)
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)
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
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)
Parameters
key- The page's key; normalised and checked.
expectedHash- The live head the form was rendered from, or null for a tombstone.
Returns
Exceptions
- This render has no signed-in visitor.
InvalidOperationException- A reserved key, a
HEAD, an ended render or a second write.
IWorker
MethodRunAsync(IWorkerContext context)
Parameters
context- What this job is and what the worker may use while it runs.
Returns
IWorkerContext
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
PropertyPath
PropertyWorker
PropertyUser
PropertyInput
null when it had none.PropertyAborted
PropertyCapabilities
MethodLog(string message)
Parameters
message- The message.
MethodLogWarning(string message)
Parameters
message- The message.
MethodLogError(string message)
Parameters
message- The message.
MethodReceiveAsync(double? waitSeconds)
Parameters
waitSeconds-
How long to wait, capped by
Pages:Jobs:MaxWaitSeconds. Omitted ornullwaits until a message arrives or the job ends.
Returns
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)
Parameters
type- What the event is, such as
deltaordone. dataJson- The event's text or JSON, bounded by
Pages:Jobs:MaxEventBytes.
MarkdownOptions
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
PropertyHeadingAnchors
id derived from its text.#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.
PropertyAutoLinks
PropertyPipeTables
NavLink
MethodNavLink(string Href, string Text, bool IsCurrent)
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.
PropertyIsCurrent
PropertyHref
Exceptions
ArgumentException- The URL is blank.
PropertyText
Exceptions
ArgumentException- The text is blank.
PageCapture
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)
Parameters
body- The outermost layer's body.
frame- The outermost layer's frame.
Exceptions
ArgumentNullException- The body or the frame is null.
PropertyBody
PageDeleteResult
MethodPageDeleteResult(bool Deleted, bool WasLive)
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
PropertyWasLive
PageDiagnostic
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)
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
nullwhen it is not known. Column- The 1-based column in the template, or
nullwhen 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
PropertyLine
null when it is not known.PropertyColumn
null when it is not known.PropertyCode
PAGE001, TEMPLATE002, CS1002 — or empty when the
message carries none.
PropertyMessage
PageDiagnosticSeverity
FieldWarning
FieldError
PageEditOutcome
FieldSaved
FieldStale
FieldUnchanged
PageEditResult
MethodPageEditResult(PageEditOutcome Outcome, string Hash, IReadOnlyList<PageDiagnostic> Diagnostics)
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
PropertyHash
PropertyDiagnostics
PropertyHasErrors
PropertyHasWarnings
PageEntry
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)
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
PropertySavedAt
PropertyHash
PropertyIsDeleted
PropertyIsReserved
PropertyIsHtml
PropertyIsAsset
PropertyIsLibrary
PropertyIsWorker
PropertyState
PropertySeed
null when the
key has no seed either side of the store.
PageFrame
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)
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
nullwhen 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
null when it set none.PropertyHead
PropertyStylesheets
PropertyAllowsScripts
PageJobEvent
MethodPageJobEvent(long Sequence, string Type, string Data)
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
deltaordone. Data- The event's text or JSON, exactly as the worker published it.
PropertySequence
PropertyType
delta or done.PropertyData
PageJobEvents
MethodPageJobEvents(IReadOnlyList<PageJobEvent> Events, long Next, bool Reset, PageJobState? State, string Failure)
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
Nextrather than treat what it missed as delivered. State- The job's state when the call answered, or
nullwhen it is gone. Failure- Why the job failed, or
nullwhen it did not.
PropertyEvents
PropertyNext
PropertyReset
Next rather than treat what it missed as delivered.
PropertyState
null when it is gone.PropertyFailure
null when it did not.PageJobInfo
MethodPageJobInfo(string Id, string Worker, string Path, PageJobState State, DateTimeOffset StartedAt, DateTimeOffset? EndedAt, string Failure)
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
nullwhile it is still running. Failure-
Why it failed, in the host's words, or
nullwhen it did not. A job starts with anulland only a failure sets it.
PropertyId
PropertyWorker
PropertyPath
PropertyState
PropertyStartedAt
PropertyEndedAt
null while it is still running.PropertyFailure
null when it did not. A job starts with a
null and only a failure sets it.
PageJobRefusal
FieldNone
FieldAnonymous
FieldReadOnly
HEAD, which reads and never writes.FieldInvalidKey
FieldOwnedBySite
FieldUnknownWorker
FieldNotAWorker
FieldQueueFull
FieldUnknownJob
FieldEnded
FieldTooManyMessages
FieldMessageTooLarge
Pages:Jobs:MaxMessageBytes.PageJobSendResult
MethodPageJobSendResult(PageJobRefusal Refusal)
Parameters
Refusal- Why it was refused, or None.
PropertyRefusal
PropertySent
PageJobStart
MethodPageJobStart(string Id, PageJobRefusal Refusal)
Parameters
Id- The new job's id, or
nullwhen it was refused. Refusal- Why it was refused, or None.
PropertyId
null when it was refused.PropertyRefusal
PropertyStarted
PageJobState
FieldQueued
FieldRunning
FieldCompleted
FieldFailed
FieldCancelled
PageKeyResolution
MethodPageKeyResolution(string Key, bool IsReserved, string Error)
Parameters
Key- The canonical key, or
nullwhen 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
nullwhen it does.
PropertyKey
null when the text names no page.PropertyIsReserved
PropertyError
null when it does.PropertyIsSuccess
PageRequest
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)
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
GETorPOST. 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
GET or POST.PropertyPath
/.PropertyQuery
PropertyForm
PropertyHeaders
PropertyCookies
PropertyQueryValues
PropertyFormValues
PageRequestExtensions
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)
Parameters
request- The request to copy.
name- The query name.
value- The value to give it; it may not be
null.
Returns
Exceptions
ArgumentNullExceptionrequestorvalueis null.ArgumentExceptionnameis blank.
MethodWithQuery(PageRequest request, IReadOnlyList<KeyValuePair<string, string>> query)
Parameters
request- The request to copy.
query- The query, in the order the caller wants it, repeated names included.
Returns
query.Exceptions
ArgumentNullExceptionrequestorqueryis null.ArgumentException- A name is blank, or a value is null.
MethodWithAnotherQuery(PageRequest request, string name, string value)
Parameters
request- The request to copy.
name- The query name.
value- The value to add; it may not be
null.
Returns
Exceptions
ArgumentNullExceptionrequestorvalueis null.ArgumentExceptionnameis blank.
MethodWithoutQuery(PageRequest request, string name)
Parameters
request- The request to copy.
name- The query name to drop.
Returns
Exceptions
ArgumentNullExceptionrequestis null.ArgumentExceptionnameis blank.
MethodWithoutQuery(PageRequest request)
Parameters
request- The request to copy.
Returns
Exceptions
ArgumentNullExceptionrequestis null.
PageResponse
MethodPageResponse(int Status, string ContentType, IReadOnlyDictionary<string, string> Headers, string Location)
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
nullwhen the page did not redirect.
PropertyStatus
200.PropertyContentType
text/html; charset=utf-8.PropertyHeaders
PropertyLocation
null when the page did not redirect.PropertyAllowsScripts
script-src 'self' on the response's
Content-Security-Policy; inline scripts stay blocked either way.
PropertyDefault
PageResponseDeprecation
FieldDeprecated
PageRevisionInfo
MethodPageRevisionInfo(string Hash, DateTimeOffset SavedAt, bool IsCurrent)
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
falsefor a tombstoned page, which has no live head.
PropertyHash
PropertySavedAt
PropertyIsCurrent
false for a
tombstoned page, which has no live head.
PageSaveResult
MethodPageSaveResult(string Hash, IReadOnlyList<PageDiagnostic> Diagnostics)
Parameters
Hash- The new revision's hash, as RevisionsAsync reports it.
Diagnostics- The compiler's author-facing answer, ordered by template position.
PropertyHash
PropertyDiagnostics
PropertyHasErrors
PropertyHasWarnings
PageSeedSummary
MethodPageSeedSummary(string Verdict, string Sentence, bool CanApply, bool CanAdopt)
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
PropertySentence
PropertyCanApply
PropertyCanAdopt
PageSessionKey
MethodPageSessionKey(string Page, string Key)
Parameters
Page- The canonical page key the value belongs to.
Key- The key that page chose.
PropertyPage
PropertyKey
PageSource
MethodPageSource(string Key, string Hash, DateTimeOffset SavedAt, string Source)
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
PropertyHash
PropertySavedAt
PropertySource
PageStreamRefusedException
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)
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
MethodPageUser(string Name)
Parameters
Name- The normalised user name from the sign-in cookie.
PropertyName
PageValue<T>
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)
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
PropertyValue
ShellAudience
FieldEveryone
FieldAnonymous
FieldOwner
ShellLink
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)
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
PropertyAudience
PropertyMatch
PropertyHref
Exceptions
ArgumentException- The URL is blank.
PropertyText
Exceptions
ArgumentException- The text is blank.
ShellMatch
FieldLeaf
FieldSubtree
ShellSection
FieldSite
FieldAdministration
UserFacingException
MethodUserFacingException(string message)
Parameters
message- The user-safe message.