The site

All assemblies · uk.osric.asp.Web · 419 types · 2,152 entries

uk.osric.asp.Web

Program

Imperative shell: wires the web host to the functional core.

SiteOptions

Where the host reaches the site it is serving.

One value, because a process that does not know its own origin cannot tell "this is us" from "this is somebody else" — and the assistant's view is the caller that needs to know. It is a policy value like every other (`code-policy-values-are-configuration`): the shipped value is the container's own loopback, where the quadlet publishes the port and its health check asks, and make run binds the same port so the shipped value is true in development too.

Plaintext is allowed only to loopback. The token a run presents over it never leaves the machine's own network namespace, which is the same trade PageCredential.AppliesTo already makes for an operator-configured credential.

FieldRecommended

The value this repository ships, for the message an operator reads.

PropertyOrigin

The origin: a scheme, a host and a port, and nothing after them.

MethodTryResolve(string path, ref string url, ref string problem)

Joins a site-relative path onto the origin.
A leading // is refused rather than joined: Uri reads it as a protocol-relative URL and would leave the site, which is the one thing this method exists to stop.

Parameters

path
A path beginning with one /, with an optional query.
url
The absolute URL to request, when the path was usable.
problem
Why the path is not a site-relative path, when it is not.

Returns

true when url names this site.

MethodFromConfiguration(IConfiguration configuration)

Reads Site.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Site into the caller's report.

Parameters

reader
A reader opened on Site, which the caller completes.

Admin

Admin.AdminIndexEndpoint

The public index of the tools the shell offers.
It answers anyone: an anonymous visitor gets the public tools, and the owner's are left out rather than answered with a redirect. The list is the shell's own — the same values the administration views' menu draws — so the index cannot offer a tool the menu has forgotten or miss one it has.

MethodHandleAsync(HttpContext context, CancellationToken cancellationToken)

Answers GET /admin.

Parameters

context
The response being written.
cancellationToken
Aborted when the request is abandoned.

Admin.AdminNavigation

The navigation landmark the administration views share.

FieldLabel

The label no other navigation landmark may repeat.

MethodNav(HttpContext context)

Renders the administration tools the shell offers.

Parameters

context
The request being answered, whose path marks the current tool.

Admin.AdminOptions

The values the admin routes read from configuration.
Read once at startup, so a missing setting stops the site rather than a page the owner opens.

PropertyChangelist

The changelist file, relative to the assembly unless it is absolute.

MethodFromConfiguration(IConfiguration configuration)

Reads Admin.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Admin into the caller's report.

Parameters

reader
A reader opened on Admin, which the caller completes.

Admin.AdminPage

The bare document the two routine seed pages are written in.
These two are the way back when the site is broken, so they cannot be rendered through a stored layout or the page pipeline: their document is written here, with no stylesheet and no navigation beyond the way back to the shell's own pages. Every other admin page is a shell document.
The links back to the shell's own pages, written under the heading.

MethodBeginAsync(HttpContext context, string title)

Writes the document's head and opens its main element.

Parameters

context
The request being answered.
title
The document's title, escaped on the way out.

MethodEndAsync(HttpContext context)

Writes the document's closing markup.

Parameters

context
The request being answered.

Returns

The write, which the caller awaits last.

Admin.ApplySeedsEndpoint

The routine seed apply: what a release moved, written on the gate and nothing else.

It walks the pack in ordinal key order. It writes every release newer row, creates every new one and records every row whose content already is the shipped seed, and it skips the rows that are not its business: in sync, deleted and retired. The first row that has drifted — edited, conflict, or unknown with content that is not the seed — stops the run, and the rows after it are not written.

Its counterpart is Admin.RestoreEndpoint: that one is the way back when the site is broken, writes everything it ships and reports every outcome. This one is the routine apply, and it stops rather than leaving a half-applied site the operator believes is applied.

MethodPreviewAsync(HttpContext context, Editor.PageEditor pages, Pages.PageSeeds seeds, IAntiforgery antiforgery)

Shows what an apply would write, and what would stop it.

Parameters

context
The request being answered.
pages
The page store, through the saver every write uses.
seeds
The pack this release ships.
antiforgery
Mints the form's token.

MethodApplyAsync(HttpContext context, Editor.PageEditor pages, Pages.PageSeeds seeds, ILoggerFactory loggers)

Writes the rows the gate allows, and stops at the first that has drifted.

Parameters

context
The request being answered.
pages
The page store, through the saver every write uses.
seeds
The pack this release ships.
loggers
Names a seed that failed.

Admin.ArchiveColumn

One column an archive table must carry, as PRAGMA table_info describes it.

MethodArchiveColumn(string Name, bool NotNull, int PrimaryKey)

One column an archive table must carry, as PRAGMA table_info describes it.

Parameters

Name
The column name, matched exactly.
NotNull
Whether the column declares NOT NULL.
PrimaryKey
Its 1-based position in the primary key, or 0 when it is not one.

PropertyName

The column name, matched exactly.

PropertyNotNull

Whether the column declares NOT NULL.

PropertyPrimaryKey

Its 1-based position in the primary key, or 0 when it is not one.

Admin.ArchiveOptions

Every bound an import archive may reach, in one place.
These bound one hostile upload; they are not a policy on the site's own pages. A large site's export can exceed MaxUploadBytes, and raising the setting is the answer, not relaxing the validation. Every value comes from Pages:Archive.

PropertyMaxUploadBytes

The most bytes one uploaded archive may be.

PropertyMaxPages

The most pages one archive may carry.

PropertyMaxCompiledBytes

The most compiled bytes one batch may hold before it commits.

PropertyStageTtlMinutes

How long an unapproved review survives.

PropertyMaxStagedImports

How many reviewed archives are held in memory.

PropertyStageTtl

The stage time-to-live as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Archive.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Archive into the caller's report.

Parameters

reader
A reader opened on Pages:Archive, which the caller completes.

Admin.ChangesEndpoint

The changelist: every commit in the deployed build, newest first.
The list is a file written by make changelist and packed beside the assembly, because the running image has no source tree and no git. Each line is a full hash and a subject, which is what lets the hash link to the commit's own page on GitHub instead of being decoration.

FieldRepositoryUrl

Where a commit's own page lives.

MethodHandleAsync(HttpContext context, Admin.AdminOptions options)

Renders the changelist.

Parameters

context
The request being answered.
options
Names the file, from Admin:Changelist.

MethodReadAsync(Admin.AdminOptions, CancellationToken)

The file's contents, or null when this build carries none.

MethodPathOf(Admin.AdminOptions)

The file's path; a relative setting is resolved beside the assembly.

MethodParse(string)

The file's lines, with a full hash recognised as a commit.

Admin.ChangesEndpoint.Commit

One line: a full hash and its subject, or text that is not a commit.

MethodCommit(string, string)

One line: a full hash and its subject, or text that is not a commit.

Admin.CopyrightEndpoint

The copyright and licence page, read from the files the build carries.
Public even though the key is under /admin: the licence of published source, and the notices for the packages the site ships, are for whoever asks. It draws the administration menu because that is where a reader finds it, as the reference page does.

MethodHandleAsync(HttpContext context, Admin.LicenceLibrary library, MarkdownRenderer markdown, CancellationToken cancellationToken)

Answers GET /admin/copyright.

Parameters

context
The response being written.
library
The files this build carries.
markdown
Renders the third-party notices, which are written in Markdown.
cancellationToken
Aborted when the request is abandoned.

Admin.ExportEndpoint

The export view: a checkbox list of live pages and a streaming download.
The list offers every live page that is addressable and not reserved — the same test the editor uses to call a page reachable — because a page on a reserved key could never be imported back, and a deleted page has no current source to export.

MethodListAsync(HttpContext context, Pages.IPageStore pages, Pages.ReservedPaths reserved, Pages.PageSeeds seeds, IAntiforgery antiforgery)

Renders the list of exportable pages.

Parameters

context
The request being answered.
pages
The page store.
reserved
The keys the site's own routes answer for.
seeds
The pack this release ships, so the selection can group by it.
antiforgery
Mints the form's token.

MethodDownloadAsync(HttpContext context, Pages.IPageStore pages, Pages.IPageStateStore state, Pages.ReservedPaths reserved, ILoggerFactory loggers)

Builds the archive from the ticked pages and writes it as a download.

Parameters

context
The request being answered.
pages
The page store.
state
The state store.
reserved
The keys the site's own routes answer for.
loggers
Names the archive in the journal.

Admin.ImportBatchStatus

Where the batch as a whole has got to.

FieldReviewing

Staged and waiting to be approved.

FieldQueued

Approved and queued for the worker.

FieldCompiling

Compiling the selected pages, with nothing written.

FieldSaving

Writing every selected page in one transaction.

FieldCommitted

Every selected page is stored.

FieldFailed

Nothing was written.

Admin.ImportEndpoint

The import views: upload and validate, review and approve, progress and results.
Nothing is written to storage until an approved batch commits in one transaction, so a rejected archive and an abandoned review leave the site exactly as it was.

FieldFormOverheadBytes

How much room the multipart envelope needs above the archive itself.

FieldArchiveField

The file part every upload must carry.

FieldIncludeField

The checkbox every selection uses.

MethodUploadFormAsync(HttpContext context, IAntiforgery antiforgery, Admin.ArchiveOptions options)

Renders the upload form.

Parameters

context
The request being answered.
antiforgery
Mints the form's token.
options
The archive options, for the size the form describes.

MethodUploadAsync(HttpContext context, Admin.PageArchiveReader reader, Admin.ImportStageStore stages, Admin.ArchiveOptions options, ILoggerFactory loggers)

Validates an uploaded archive and stages it, or explains why it was refused.

Parameters

context
The request being answered.
reader
The archive reader.
stages
Where a validated archive is staged.
options
The archive options.
loggers
Names a refused upload in the journal.

MethodReviewAsync(HttpContext context, Admin.ImportStageStore stages, Pages.IPageStore pages, IAntiforgery antiforgery)

Renders the staged archive for review.

Parameters

context
The request being answered.
stages
The staged archives.
pages
The page store, for what the site already holds.
antiforgery
Mints the form's token.

MethodApproveAsync(HttpContext context, Admin.ImportStageStore stages, Admin.ImportQueue queue, Pages.ReservedPaths reserved, ILoggerFactory loggers)

Approves the ticked pages and hands the batch to the worker.

Parameters

context
The request being answered.
stages
The staged archives.
queue
The import queue.
reserved
The keys the site's own routes answer for.
loggers
Names a refused approval in the journal.

MethodProgressAsync(HttpContext context, Admin.ImportStageStore stages)

Renders the batch's progress and results, refreshing while it runs.

Parameters

context
The request being answered.
stages
The staged archives.

Admin.ImportPageResult

One page's place in a running import.

MethodImportPageResult(PagePath Path, Admin.ImportPageStatus Status, IReadOnlyList<PageDiagnostic> Diagnostics)

One page's place in a running import.

Parameters

Path
The page being imported.
Status
How far it got.
Diagnostics
The compiler's diagnostics, when it did not compile cleanly.

PropertyPath

The page being imported.

PropertyStatus

How far it got.

PropertyDiagnostics

The compiler's diagnostics, when it did not compile cleanly.

Admin.ImportPageStatus

What became of one page in an import.

FieldWaiting

Not compiled yet, or not reached after the batch failed.

FieldStoredAsSource

Has no code, so it is stored and served as source.

FieldCompiled

Compiled cleanly.

FieldCompiledWithWarnings

Compiled, with warnings.

FieldCompiledWithErrors

Did not compile; it is still stored, with its diagnostics.

FieldCompilerFault

The compiler itself failed; the source is kept without an image.

FieldLibrary

Checked as a library, with nothing to report.

FieldLibraryWithIssues

Checked as a library, and its check reported something.

Admin.ImportProcessor

Compiles an approved batch and commits it in one transaction.

The split is the whole design: compilation writes nothing, so a compile failure, a compiler fault, a cap or a host crash leaves storage untouched; then the whole batch is written in one transaction. A page that does not compile is a stored revision with diagnostics, not a reason to stop.

Records page.import.duration for the batch as a whole.

MethodImportProcessor(Pages.PageImageBuilder, Pages.IPageBatchStore, Pages.PageLibraries, Pages.PageMetrics, Admin.ArchiveOptions, ILogger<Admin.ImportProcessor>)

Compiles an approved batch and commits it in one transaction.

The split is the whole design: compilation writes nothing, so a compile failure, a compiler fault, a cap or a host crash leaves storage untouched; then the whole batch is written in one transaction. A page that does not compile is a stored revision with diagnostics, not a reason to stop.

Records page.import.duration for the batch as a whole.

MethodProcessAsync(Admin.ImportStage stage, CancellationToken cancellationToken)

Runs one approved batch.

Parameters

stage
The stage holding the archive and its results.
cancellationToken
Cancels the batch.

Admin.ImportQueue

The bounded queue of imports waiting for the worker.
The queue refuses an import that does not fit rather than growing without bound. With one editor this is a backstop, not a feature — the worker runs one job at a time because there is one compile slot behind it.

MethodImportQueue(Admin.ArchiveOptions options)

The bounded queue of imports waiting for the worker.
The queue refuses an import that does not fit rather than growing without bound. With one editor this is a backstop, not a feature — the worker runs one job at a time because there is one compile slot behind it.

Parameters

options
The archive options, whose staged-import count bounds the queue.

Admin.ImportStage

One staged archive and its job state, mutated under one lock.
A stage is in memory only: it never touches disk, and a restart simply forgets it. Everything that reads or writes the job state takes the lock, so the progress page sees a whole picture rather than a half-applied one.

MethodImportStage(string id, IReadOnlyList<Admin.PageArchiveEntry> pages, DateTimeOffset createdAt)

Creates a stage over a validated archive.

Parameters

id
The stage's identifier, from the store.
pages
The validated pages.
createdAt
When the archive was staged, for the time-to-live.

PropertyId

The stage's identifier.

PropertyPages

The validated pages, in key order.

PropertyCreatedAt

When the archive was staged.

PropertyIsRunning

Whether the stage has been approved and handed to the worker.

MethodFind(PagePath path)

Finds a page the archive carries.

Parameters

path
The canonical key.

MethodTryApprove(IReadOnlyList<PagePath> selected)

Marks the stage approved and queued, unless a worker already has it.
A finished stage accepts another approval: the review offers a retry after a failure, and a second import of the same archive is an ordinary new revision rather than a special case.

Parameters

selected
The pages the approval ticked, in key order.

Returns

false when this stage is already importing.

MethodUnqueue()

Puts the stage back to "not approved" after the queue refused it.

MethodBeginCompiling()

Records that compilation has started.

MethodBeginSaving()

Records that the single transaction has started.

MethodRecord(Admin.ImportPageResult result)

Records one page's compile result.

Parameters

result
The result to record.

MethodCommit(string message)

Records that every selected page was stored.

Parameters

message
A sentence for the reader.

MethodFail(string message, IReadOnlyList<PagePath> refused)

Records that nothing was stored.
A page still marked Waiting was not compiled after the failure.

Parameters

message
A sentence naming the reason.
refused
The pages whose merged state would not fit, when that is the reason.

MethodSnapshot()

Takes a consistent picture of the stage.

Admin.ImportStageSnapshot

A consistent picture of a stage, taken under the stage's lock.

MethodImportStageSnapshot(Admin.ImportBatchStatus Status, IReadOnlyList<PagePath> Selected, IReadOnlyList<Admin.ImportPageResult> Results, IReadOnlyList<PagePath> Refused, string Message)

A consistent picture of a stage, taken under the stage's lock.

Parameters

Status
Where the batch has got to.
Selected
The pages the approval ticked, in key order.
Results
One result per selected page, filled in as the worker runs.
Refused
The pages whose merged state would not fit, when that is why the batch failed.
Message
A sentence for the reader, when the outcome needs one.

PropertyStatus

Where the batch has got to.

PropertySelected

The pages the approval ticked, in key order.

PropertyResults

One result per selected page, filled in as the worker runs.

PropertyRefused

The pages whose merged state would not fit, when that is why the batch failed.

PropertyMessage

A sentence for the reader, when the outcome needs one.

Admin.ImportStageStore

Holds the reviewed archives, expiring them on a time-to-live and a count.
A stage lives in memory only. The oldest is evicted when a new one would exceed MaxStagedImports, and a stage older than StageTtl is gone by the time anybody asks for it, so an abandoned upload cannot sit in memory indefinitely.

MethodImportStageStore(Admin.ArchiveOptions, TimeProvider)

Holds the reviewed archives, expiring them on a time-to-live and a count.
A stage lives in memory only. The oldest is evicted when a new one would exceed MaxStagedImports, and a stage older than StageTtl is gone by the time anybody asks for it, so an abandoned upload cannot sit in memory indefinitely.

FieldIdLength

The length of a stage identifier: 32 hexadecimal characters.

PropertyCount

How many stages are held; a fixture uses it to prove a rejection staged nothing.

MethodCreate(IReadOnlyList<Admin.PageArchiveEntry> pages)

Stages a validated archive under a fresh identifier.

Parameters

pages
The validated pages.

Returns

The new stage.

MethodGet(string id)

Finds a live stage.

Parameters

id
The identifier from the URL.

Returns

The stage, or null when it is unknown, malformed or expired.

MethodIsWellFormed(string id)

Whether text could be a stage identifier at all.
Checked before the dictionary is consulted, so a crafted path cannot reach a lookup and the route answers 404 for anything a stage could never be named.

Parameters

id
The text from the URL.

Admin.ImportWorker

Runs approved imports one at a time, each in its own scope.
One at a time because CompileSlots defaults to one: a second import would only wait behind the first, and serialising the compiles keeps the progress page honest. The processor is scoped because Pages.PageImageBuilder and the batch store are.

MethodImportWorker(Admin.ImportQueue, Admin.ImportStageStore, IServiceScopeFactory, ILogger<Admin.ImportWorker>)

Runs approved imports one at a time, each in its own scope.
One at a time because CompileSlots defaults to one: a second import would only wait behind the first, and serialising the compiles keeps the progress page honest. The processor is scoped because Pages.PageImageBuilder and the batch store are.

Admin.LicenceLibrary

The copyright and licence files this build carries, read once.

The deployed image has no checkout, so the files are packed beside the assembly the way the changelist and the third-party notices are. Reading them is the whole point: a page that copied their text would be a second copy to keep in step, which is the drift this replaced.

A missing file is not an error. A build that did not come through the Makefile carries none, and the page names what it lacks rather than failing; each file is read lazily and kept.

MethodLicenceLibrary(string directory)

Reads the files beside a directory.

Parameters

directory
The directory the build copied them into, normally the assembly's own.

PropertySiteLicence

The site's own licence text (LICENSE), or null when the build does not carry it.

PropertyThirdPartyNotices

The notice the image carries for the packages it ships, or null.

PropertyReuse

The REUSE annotation file, or null.

PropertyLicences

The licence texts in LICENSES, in name order; empty when the folder is not carried.

Admin.LicenceText

One licence text the build carries.

MethodLicenceText(string Name, string Text)

One licence text the build carries.

Parameters

Name
The licence's name, from its file name: MIT, ISC, BSD-3-Clause.
Text
The text exactly as the file holds it.

PropertyName

The licence's name, from its file name: MIT, ISC, BSD-3-Clause.

PropertyText

The text exactly as the file holds it.

Admin.PageArchiveEntry

One page an archive carries: its key, its source, its seed anchor and the state beside it.

MethodPageArchiveEntry(PagePath Path, string Source, IReadOnlyList<Pages.PageStateValue> State, string SeedHash)

One page an archive carries: its key, its source, its seed anchor and the state beside it.

Parameters

Path
The canonical key. It is written unchanged; export never rewrites a key.
Source
The template text exactly as stored.
State
The page's state values, in ordinal key order; empty when it has none.
SeedHash
The seed the page's content is anchored to, or null when it has no record.

PropertyPath

The canonical key. It is written unchanged; export never rewrites a key.

PropertySource

The template text exactly as stored.

PropertyState

The page's state values, in ordinal key order; empty when it has none.

PropertySeedHash

The seed the page's content is anchored to, or null when it has no record.

PropertySourceBytes

The source size in UTF-8 bytes, which is what the archive file pays for it.

PropertyStateKeys

How many state keys the page carries.

Admin.PageArchiveFormat

The archive's identity and shape, in the one place the writer and the reader agree on.

An archive is a SQLite database rather than a zip: it already sits underneath the site's storage provider, a row has a Path value instead of an entry name, and the format carries its own version. ApplicationId is the format identity and Version the format version, so a reader refuses a file before it reads a row.

The schema is deliberately not the site's own: it ships source and state only. Revisions carry images, symbols, hashes and runtime ids that belong to the machine that built them, so they stay where they were made.

FieldApplicationId

The application_id every archive carries: the bytes uoas.

FieldVersion

The format version this build writes.
Version 2 adds SeedHash; a version 1 archive is still read, with no provenance on any key. A version 2 archive cannot be read by a build that knows only version 1, which is the right way round: the older build refuses the file instead of silently dropping the anchor.

FieldPagesTable

The table holding one row per page.

FieldPageStateTable

The table holding one row per page state key.

FieldCreatePages

The statement that creates PagesTable.
Path is the canonical page key, root included, and Source is the template text exactly as stored. WITHOUT ROWID because the key is the whole row identity.

FieldCreatePagesV1

The version 1 table, which carries source and nothing else.

FieldCreatePageState

The statement that creates PageStateTable.
The same shape as the site's own state table: Value is the stored JSON text, so a stored null is the four characters null and a page with no state has no rows.

MethodPagesColumns(int version)

The columns PagesTable must have for a format version, in order.

Parameters

version
The archive's user_version, which must be 1 or 2.

PropertyPageStateColumns

The columns PageStateTable must have, in order.

Admin.PageArchiveReadResult

The pages an archive carries, or the reasons it was refused.

MethodPageArchiveReadResult(IReadOnlyList<Admin.PageArchiveEntry> Pages, IReadOnlyList<string> Problems)

The pages an archive carries, or the reasons it was refused.

Parameters

Pages
The validated pages, in key order; empty when Problems is not.
Problems
Every rule the archive broke, up to the reporting limit.

PropertyPages

The validated pages, in key order; empty when Problems is not.

PropertyProblems

Every rule the archive broke, up to the reporting limit.

PropertySucceeded

Whether every row passed every rule.

Admin.PageArchiveReader

Reads an uploaded archive as hostile input, and stages nothing unless every rule holds.

The file reaches SQLite's parser, which is a real boundary: it is deserialized read-only into a throwaway in-memory connection, query_only and trusted_schema are set before any query, the two tables must be ordinary tables with exactly the expected columns, quick_check runs once, and every row is validated before anything is returned.

Validation is all or nothing. Problems are collected — up to ten — only so the error page can show several at once; each one is independently fatal, and nothing is skipped, renamed or repaired.

MethodPageArchiveReader(Admin.ArchiveOptions, Pages.PageStorageOptions, Pages.ReservedPaths, ILogger<Admin.PageArchiveReader>)

Reads an uploaded archive as hostile input, and stages nothing unless every rule holds.

The file reaches SQLite's parser, which is a real boundary: it is deserialized read-only into a throwaway in-memory connection, query_only and trusted_schema are set before any query, the two tables must be ordinary tables with exactly the expected columns, quick_check runs once, and every row is validated before anything is returned.

Validation is all or nothing. Problems are collected — up to ten — only so the error page can show several at once; each one is independently fatal, and nothing is skipped, renamed or repaired.

FieldMaxProblems

How many problems are reported before the scan stops.

MethodRead(byte[] archive)

Reads and validates an archive.

Parameters

archive
The uploaded bytes.

Returns

The candidates, or the problems that rejected them.

Admin.PageArchiveWriter

Builds a page archive in memory and hands back its serialized bytes.

The database is created with Data Source=:memory:, filled in one transaction, and then serialized with sqlite3_serialize, so neither direction needs a temporary file. Rows are written in key order; the file layout itself is SQLite's business and is not promised to be byte-stable between versions.

Nothing here reads the site's storage: the caller hands over the pages it has already read, which is what makes a storage failure a readable error page rather than half a download.

MethodWrite(IReadOnlyList<Admin.PageArchiveEntry> pages)

Builds the archive and returns the serialized database.

Parameters

pages
The pages to write, ordered or not; the writer sorts by key.

Returns

The bytes of a SQLite database holding Admin.PageArchiveFormat's two tables.

Admin.RestoreEndpoint

The emergency restore: every seed back to its bundled source in one POST.

This is the way back when a stored page that the site itself needs — the editor, its sheet, its module or the layout — will not load. It is not a reset and not an import: it only writes the pages the release ships, a seed that already matches is not written, and a page the owner made is never touched. Every write goes through SaveAsync, so it compiles before it stores exactly as any other save does.

The document is written here rather than through Html.ShellDocument, and it carries no stylesheet and no script. The shell's document always links /site.css, which is a seeded page the owner can break — a single * { display: none; } would hide the one page that can put it back — so the recovery page depends on nothing it is there to recover.

MethodPreviewAsync(HttpContext context, Editor.PageEditor pages, Pages.PageSeeds seeds, IAntiforgery antiforgery)

Shows every seed and what restoring it would change.

Parameters

context
The request being answered.
pages
The page store, through the saver every write uses.
seeds
The pack this release ships.
antiforgery
Mints the form's token.

MethodRestoreAsync(HttpContext context, Editor.PageEditor pages, Pages.PageSeeds seeds, ILoggerFactory loggers)

Restores every seed that differs, reporting each one rather than stopping at a failure.

Parameters

context
The request being answered.
pages
The page store, through the saver every write uses.
seeds
The pack this release ships.
loggers
Names a seed that failed.

Admin.ScrubEndpoint

Scrubs a deleted page and the history it retained, once its key is typed.

Scrubbing is the one page operation that cannot be undone, so it stays in the shell rather than becoming a page capability: the confirmation is a view a stored page cannot shadow, and the typed key is checked here rather than by whatever page is currently the editor.

Only a deleted page can be scrubbed. A live page answers 409 and names the delete that has to come first, so the destructive request is never the first one to touch a page that is still being served.

MethodConfirmAsync(HttpContext context, Editor.PageEditor pages, IAntiforgery antiforgery)

Shows the confirmation for the page named by the route.

Parameters

context
The request being answered.
pages
The page store.
antiforgery
Mints the form's token.

MethodScrubAsync(HttpContext context, Editor.PageEditor pages, ILoggerFactory loggers)

Scrubs the page named by the route, if the typed key matches.

Parameters

context
The request being answered.
pages
The page store.
loggers
Names the log category.

Admin.SqliteStatement

Runs one statement against an archive's connection.

MethodExecute(SqliteConnection connection, string sql)

Executes a statement that returns no rows.

Parameters

connection
The connection to run it on.
sql
The SQL to run.

Assistant

Assistant.AccountBalanceClient

Reads the provider's DeepSeek-shaped /user/balance endpoint.
The balance is an aside on a page that has other work to do, so every failure — an error status, a timeout, an unreachable host, a body that is not the balance JSON — is a reason rather than an exception. The caller decides what the reason is worth: the page says the provider did not report a balance, and the sampler logs a change. The provider's body is never returned or logged: it is a provider's text, and the status is the whole diagnosis.

MethodAccountBalanceClient(HttpClient, Assistant.AssistantOptions)

Reads the provider's DeepSeek-shaped /user/balance endpoint.
The balance is an aside on a page that has other work to do, so every failure — an error status, a timeout, an unreachable host, a body that is not the balance JSON — is a reason rather than an exception. The caller decides what the reason is worth: the page says the provider did not report a balance, and the sampler logs a change. The provider's body is never returned or logged: it is a provider's text, and the status is the whole diagnosis.

MethodGetAsync(CancellationToken)

Reads the provider's balance.

Inherited from Assistant.IAccountBalanceClient.GetAsync.

Parameters

cancellationToken
Cancelled when the caller stops waiting.

Returns

The balance with its reason, which is never an exception and never a log entry.

Assistant.AccountBalanceSampler

Samples the provider account's balance on a clock and hands it to the gauge.
The gauge reports the last sample, so a scrape never causes an outbound call and a slow provider never holds one. A failed sample keeps the previous value; the reason is logged when it changes, so a provider without a balance route costs one line rather than one per interval.

MethodAccountBalanceSampler(IServiceScopeFactory, Assistant.AssistantMetrics, Assistant.AssistantOptions, ILogger<Assistant.AccountBalanceSampler>)

Samples the provider account's balance on a clock and hands it to the gauge.
The gauge reports the last sample, so a scrape never causes an outbound call and a slow provider never holds one. A failed sample keeps the previous value; the reason is logged when it changes, so a provider without a balance route costs one line rather than one per interval.

MethodSampleAsync(CancellationToken cancellationToken)

Reads one sample and records what it can read.

Parameters

cancellationToken
Cancelled when the host stops.

Assistant.ApprovalRequest

A flagged tool call the owner is asked to allow or refuse.

MethodApprovalRequest(string Name, string Description, string Arguments)

A flagged tool call the owner is asked to allow or refuse.

Parameters

Name
The tool the call names.
Description
What the tool does, as the model was told.
Arguments
The call's arguments, exactly as the model sent them.

PropertyName

The tool the call names.

PropertyDescription

What the tool does, as the model was told.

PropertyArguments

The call's arguments, exactly as the model sent them.

Assistant.AssistantConversationPage

The conversation page: the transcript, the compose box and the figures under them.
The endpoint answers and owns the routes; the markup a reader sees lives here, so the page can be read as markup rather than as a method between two routes. Every figure on it is one the run publishes or the store holds, so a live row and a reloaded one cannot disagree.

MethodWriteInterruptAsync(HttpContext, Assistant.OwnerInterrupt, AntiforgeryTokenSet, long)

Writes the card a run is stopped on, by the kind the record names.
Rendered from the record rather than from the event stream, so a reload or another device shows the same card, and the words are the ones the live event carried. The record says what kind the run waits on, which is why the route needs no kind of its own.

MethodWriteContinuationAsync(HttpContext, Assistant.OwnerInterrupt, Assistant.ContinuationRequest, AntiforgeryTokenSet, long)

Writes the question a run that ran out of a budget asked the owner.

Assistant.AssistantEndpoint

Serves the assistant page and the JSON endpoints its stream and approvals use.

MethodInterruptAsync(HttpContext, long, string, Assistant.IConversationStore, Assistant.OwnerInterruptCoordinator)

Resolves the run's pending interrupt from whichever form the owner submitted.
The route does not name the kind: the run waits on one thing at a time and the record says what it is, so the body is parsed against the record rather than against a second copy in the URL. A field the kind does not expect, a field it needs and did not get, or a tool call id that is not the record's is a stale form, and it is refused before anything is written.

MethodMessageContentAsync(HttpContext, long, long, Assistant.IConversationStore)

Serves one stored assistant message as the restricted HTML the transcript shows.
The live transcript streams plain text because a delta is not a document, then asks for this route when the step completes. The renderer is the only writer, so a live step and the reload that follows the run cannot disagree about what Markdown is allowed.

MethodValidatedOwnerAsync(HttpContext context, long id, Assistant.IConversationStore conversations, string expiredTitle)

Validates a posted conversation form, or answers it and returns null.

Parameters

context
The request being answered.
id
The conversation the form names.
conversations
The store the conversation is looked up in.
expiredTitle
What the refusal is about, for the invalid-form message.

Returns

The signed-in account, or null when a refusal has already been written.

Assistant.AssistantFetcher

Gives the assistant the same bounded outbound HTTP as a page, with no allow-list.

A GET only: neither tool has a method or header argument. The URL rules, redirects, decoding and response cap are Pages.OutboundFetcher's, so the assistant cannot reach a connection a page cannot (`pages-outbound-fetch`).

view is the same transport with one credential: the run's token, which Pages.ViewCredential offers to Site:Origin and to nothing else, hop by hop. A redirect off that origin drops the header, so a page cannot take the run's identity anywhere.

MethodAssistantFetcher(SiteOptions, Pages.OutboundFetcher)

Gives the assistant the same bounded outbound HTTP as a page, with no allow-list.

A GET only: neither tool has a method or header argument. The URL rules, redirects, decoding and response cap are Pages.OutboundFetcher's, so the assistant cannot reach a connection a page cannot (`pages-outbound-fetch`).

view is the same transport with one credential: the run's token, which Pages.ViewCredential offers to Site:Origin and to nothing else, hop by hop. A redirect off that origin drops the header, so a page cannot take the run's identity anywhere.

MethodFetchAsync(string, CancellationToken)

GETs url anonymously and returns the response, or a failure value.

Inherited from Assistant.IAssistantFetcher.FetchAsync.

Parameters

url
An absolute http or https URL.
cancellationToken
Cancelled when the tool's budget or the run ends.

MethodViewAsync(string, Authentication.ViewToken, CancellationToken)

GETs this site and answers the response itself, authenticated as the run's owner.

Inherited from Assistant.IAssistantFetcher.ViewAsync.

The answer is the transport's own — every header, the body's bytes, and the redirects it took — because a view that summarised the response would be a second guess at what the page did.

Parameters

url
An absolute URL on Site:Origin, resolved by the caller.
token
The run's view token, which the fetcher attaches to that origin alone.
cancellationToken
Cancelled when the tool's budget or the run ends.

Assistant.AssistantMemoryEndpoint

The owner's page for the assistant's memory: list, edit, pin and forget.
The page is shell code and one document per response, like the editor and /admin/status: no script, every mutating form carrying the antiforgery pair, and every write going through EditAsync or ForgetAsync rather than through a second set of rules (`assistant-memory-page`). The owner is always the signed-in account, so a wrong owner and a missing memory answer the same way.

FieldPath

The page's own route, which the assistant's navigation links to.

MethodListAsync(HttpContext context, Assistant.IMemoryStore memories, IAntiforgery antiforgery, Assistant.AssistantOptions options)

Lists the owner's memories, grouped by kind and pinned first inside a kind.

Parameters

context
The response being written.
memories
The store the memories are read from.
antiforgery
Mints the token every row's form carries.
options
The owner's cap, for the count.

MethodSaveAsync(HttpContext context, long id, Assistant.IMemoryStore memories, IAntiforgery antiforgery, Assistant.AssistantOptions options)

Saves one memory's content, kind and pin, refusing a stale version.
A refusal re-renders the list rather than answering with a bare error page, because the textarea is the only copy of what the owner typed: a `400` keeps the submitted text and a `409` shows the content the assistant left behind (`assistant-memory-page`).

Parameters

context
The response being written.
id
The memory being saved.
memories
The store the memory is read from and written to.
antiforgery
Mints the token the re-rendered forms carry.
options
The owner's cap, for the count and the row's cap.

MethodForgetConfirmationAsync(HttpContext context, long id, Assistant.IMemoryStore memories, IAntiforgery antiforgery)

Asks before a memory is forgotten.

Parameters

context
The response being written.
id
The memory the confirmation is about.
memories
The store the memory is read from.
antiforgery
Mints the token the delete's form carries.

MethodForgetAsync(HttpContext context, long id, Assistant.IMemoryStore memories)

Deletes a memory the owner has confirmed.

Parameters

context
The response being written.
id
The memory to forget.
memories
The store the memory is deleted from.

Assistant.AssistantMetrics

The meter and instruments that describe assistant runs.

PropertyInstruments

Every instrument this meter registers, in the order the page lists them.
The catalogue maps each of these to exactly one panel, and AssistantMetricsTests listens to the meter to prove this list and the registrations below agree.

FieldStepBuckets

Buckets for assistant.run.steps, in steps.
A run cannot take more steps than Assistant:MaxSteps, and the top boundary is past it, so the run that exhausted its steps is drawn rather than counted under `+Inf` (`metrics-one-panel-per-instrument`).

FieldToolCallBuckets

Buckets for assistant.run.tool_calls, in calls.
The top boundary is past Assistant:MaxToolCalls for the same reason (`metrics-one-panel-per-instrument`).

FieldRunDurationBuckets

Buckets for assistant.run.duration, in seconds.
A run's length has no cap: Assistant:RunTimeoutSeconds bounds the provider going quiet, not the run (`assistant-deadlines-bound-silence`), so this scale is sized for the work — minutes, up to an hour. The page scale stops at ten seconds, which is why every run used to land in `+Inf`.

FieldProviderBuckets

Buckets for the provider waits, in seconds: the first token and the whole request.
Both waits are bounded by the same silence timeout, Assistant:RequestTimeoutSeconds, so they share one scale whose top boundary is past it (`metrics-one-panel-per-instrument`): a wait that reached the deadline is a real bucket, and the row that says so is the one worth reading.

FieldToolDurationBuckets

Buckets for assistant.tool.duration, in seconds.
A tool call is usually a few milliseconds of our own work, and bounded by Assistant:ToolTimeoutSeconds when it is not; the top boundary is past that cap (`metrics-one-panel-per-instrument`).

FieldEstimateErrorBuckets

Buckets for assistant.context.estimate.error, in tokens.
The margin is one of the boundaries — 27,525 tokens is three percent of the 917,504-token prompt budget — so whatever lands above it is the step that spent more than the estimate allows. The same trick the step and tool-call buckets use: draw the cap rather than hide the overrun under +Inf (`metrics-one-panel-per-instrument`).

FieldMemoryCountBuckets

Buckets for the memory instruments: how many were recalled and how large they were.

FieldUnknownTool

The tool tag recorded when a call names no registered tool.
A tool name is model-supplied, so tagging a made-up or mistyped name verbatim would mint one time series per value — the same trap as tagging a render that found no page with the path the caller typed. The transcript still carries the real name; the metric only needs to show that a call was refused.

FieldNoKind

The kind tag recorded for a write that had no kind, which includes every refusal.

FieldShapedMasked

An old payload was masked so the request would fit.

FieldShapedTrimmed

Whole turns were dropped so the request would fit.

FieldExhaustedContext

Our own estimate of the request stopped the run before it was sent.

FieldExhaustedProvider

The provider's window rejected the request.

FieldExhaustedOutput

The reply reached the tokens its request left for it.

MethodRecordTool(ToolDefinition tool, bool success, TimeSpan duration)

Records one tool call under a registered tool's name, or UnknownTool when tool is null.

Parameters

tool
The definition the call resolved to, or null when it named no registered tool. A definition rather than a name, so a model-supplied string cannot become a label.
success
Whether the call succeeded.
duration
How long the call took.

MethodRecordEstimateError(long estimate, long actual)

Records how far one step's estimate was from the count the provider reported.
The magnitude is the figure; the direction is the label. under is the one that can breach the budget, so a rising share of it is the signal to revisit the margin.

Parameters

estimate
The tokens the step's request was estimated at.
actual
The prompt tokens the provider counted for it.

MethodRecordShaped(string kind)

Records that the planner had to change a request so it would fit.

Parameters

kind
One of ShapedMasked or ShapedTrimmed.

MethodRecordBudgetExhausted(string cause)

Records that a run stopped on a budget.

Parameters

cause
One of ExhaustedContext, ExhaustedProvider or ExhaustedOutput.

MethodRecordToolTruncated(string tool)

Records that one tool result was truncated at its cap.

Parameters

tool
The registered tool's name, or UnknownTool.

MethodRecordMemoryRecall(int memories, int characters)

Records what one run recalled: how many memories and how many characters.

Parameters

memories
The memories the run was given.
characters
What the block cost.

MethodRecordMemoryWrite(string operation, MemoryKind? kind, bool success)

Records one memory write.

Parameters

operation
The tool: remember, update or forget.
kind
The kind written, or null for a refusal, where the kind may be what was wrong: NoKind is the tag instead.
success
Whether the store changed.

MethodRecordBalance(IReadOnlyList<Assistant.CurrencyCredit> credits)

Records the provider's credit, one measurement per currency.

Parameters

credits
The currencies the last sample could read.

Assistant.AssistantNavigation

The assistant's own menu: its three views, with the one being shown marked.
It is the assistant's menu rather than a site capability: no page asks for it, and when the assistant becomes a page this moves or is replaced with the page's own menu.

FieldLabel

The label no other navigation landmark may repeat.

MethodNav(HttpContext context)

Renders the assistant's menu for the request being answered.

Parameters

context
The request whose path decides the current item.

Assistant.AssistantOptions

The assistant's configuration: provider, model and limits.
Every value comes from Assistant and none has a fallback: a missing or unusable one stops the site at startup. ApiKey is required unless the provider does not need one, which AssistantOptions.RequireApiKey says.

PropertyModelsPath

The path the provider publishes its model list on, such as /models.

PropertyModelsTimeoutSeconds

How long the model list read waits for the provider before it gives up.

PropertyMinOutputTokens

The floor under a reply, in tokens. The window the provider reports is shared between the prompt and the reply, so what the prompt leaves is the reply's allowance, capped at the provider's own maximum and never below this.

PropertyBalanceTimeoutSeconds

How long the account balance panel waits for the provider before it shows nothing.

PropertyBalanceSampleSeconds

How often the balance sampler reads the provider account's credit.

PropertyMaxPageChars

The most characters a stored page may carry: the page store's bound, not a context rule.

PropertyMaxToolArgumentChars

The most characters one tool call's arguments may carry. It must exceed MaxPageChars with room for the envelope, because a page the store accepts must be writable through a tool.

PropertyMaxMemoriesPerOwner

The most memories one owner may hold; past this remember refuses.

PropertyMaxMemoryChars

The longest memory, in characters. One longer is refused, never truncated.

PropertyMaxMemorySearchResults

The most candidates a memory search ranks, for recall and for the tool.

PropertyMaxMemoryQueryTerms

The most terms one message contributes to a recall query.

PropertyWritablePathPrefix

A page-key prefix the assistant may write within; blank means the whole site.

PropertyMaxSearchMatches

What one search_pages call may return.

PropertyDefaultListLimit

Rows a listing answers with when the caller names no limit.

PropertyMaxListLimit

The most rows one listing will answer with.

PropertyShellMatchLimit

Lines one virtual-shell grep may show before it says there are more.

PropertyShellDefaultLines

Lines head and tail show when no count is given.

MethodFromConfiguration(IConfiguration configuration)

Reads Assistant.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Assistant into the caller's report.

Parameters

reader
A reader opened on Assistant, which the caller completes.

Assistant.AssistantOptionsValidator

Rejects an assistant configuration whose values cannot all be true at once.
The reader owns "present, a number, inside its range" for every key; this owns the rules a range cannot express.

MethodValidate(string, Assistant.AssistantOptions)

Inherited from IValidateOptions`1.Validate.

Assistant.ContinuationRequest

A spent budget the owner is asked to top up.

MethodContinuationRequest(string Budget, int Limit, int Window, string Message)

A spent budget the owner is asked to top up.

Parameters

Budget
Which budget ran out, in Assistant.RunBudget's words.
Limit
The limit the run reached.
Window
What continuing buys.
Message
The sentence the card shows.

PropertyBudget

Which budget ran out, in Assistant.RunBudget's words.

PropertyLimit

The limit the run reached.

PropertyWindow

What continuing buys.

PropertyMessage

The sentence the card shows.

Assistant.Conversation

A stored conversation: its owner, title and approval mode.

Assistant.ConversationListItem

One row of the conversation list, with the run still in progress.

MethodConversationListItem(long, string, string, DateTimeOffset, string)

One row of the conversation list, with the run still in progress.

Assistant.CurrencyCredit

One currency's credit, as the balance gauge reports it.

MethodCurrencyCredit(string Currency, double Amount)

One currency's credit, as the balance gauge reports it.

Parameters

Currency
The currency code the provider reported.
Amount
The total available credit in that currency.

PropertyCurrency

The currency code the provider reported.

PropertyAmount

The total available credit in that currency.

Assistant.IAccountBalanceClient

Reads the provider account's current balance for the conversation page and the sampler.

MethodGetAsync(CancellationToken cancellationToken)

Reads the provider's balance.

Parameters

cancellationToken
Cancelled when the caller stops waiting.

Returns

The balance with its reason, which is never an exception and never a log entry.

Assistant.IAssistantFetcher

The outbound GETs the assistant's tools offer: fetch and view.

MethodFetchAsync(string url, CancellationToken cancellationToken)

GETs url anonymously and returns the response, or a failure value.

Parameters

url
An absolute http or https URL.
cancellationToken
Cancelled when the tool's budget or the run ends.

MethodViewAsync(string url, Authentication.ViewToken token, CancellationToken cancellationToken)

GETs this site and answers the response itself, authenticated as the run's owner.
The answer is the transport's own — every header, the body's bytes, and the redirects it took — because a view that summarised the response would be a second guess at what the page did.

Parameters

url
An absolute URL on Site:Origin, resolved by the caller.
token
The run's view token, which the fetcher attaches to that origin alone.
cancellationToken
Cancelled when the tool's budget or the run ends.

Assistant.IChatCompletionClient

Streams a completion from the configured provider.

Assistant.IConversationStore

Stores conversations, their messages, runs and tool approvals.

MethodAppendMessageAsync(long, string, Assistant.MessageInput, CancellationToken)

Appends a message and returns its stored id, or null when the conversation is gone.

MethodOpenInterruptAsync(string runId, string kind, string toolCallId, string requestJson, CancellationToken cancellationToken)

Opens the run's one interrupt and moves the run to awaiting_owner.

Parameters

runId
The run that is stopping.
kind
One of Assistant.OwnerInterruptKind.
toolCallId
The call the wait belongs to, or null.
requestJson
What the owner is shown, as Assistant.InterruptPayloads writes it.
cancellationToken
The run's token.

Returns

Whether the interrupt was opened; false when the run was not running or already had one.

MethodGetInterruptAsync(string runId, CancellationToken cancellationToken)

The run's interrupt, whatever its state, or null.

Parameters

runId
The run whose interrupt is read.
cancellationToken
The run's token.

MethodGetPendingInterruptAsync(long conversationId, string owner, CancellationToken cancellationToken)

The conversation's pending interrupt, or null when the owner is not being waited on.

Parameters

conversationId
The conversation.
owner
The signed-in owner.
cancellationToken
The request's token.

MethodResolveInterruptAsync(long conversationId, string owner, string runId, string kind, string toolCallId, string resolutionJson, CancellationToken cancellationToken)

Records the owner's resolution and moves the run back to running.

Parameters

conversationId
The conversation.
owner
The signed-in owner.
runId
The run whose interrupt is resolved.
kind
The kind the caller read, checked against the record.
toolCallId
The call the caller read, checked against the record.
resolutionJson
What the owner gave, as Assistant.InterruptPayloads writes it.
cancellationToken
The request's token.

MethodContinueRunAsync(long conversationId, string owner, string runId, CancellationToken cancellationToken)

Resolves a run's continuation interrupt and widens the budget it ran out of.

Parameters

conversationId
The conversation.
owner
The signed-in owner.
runId
The paused run.
cancellationToken
The request's token.

Returns

Whether a pending continuation was resolved; false when the run is not waiting on one.

MethodFailPendingInterruptAsync(string runId, string failureCode, CancellationToken cancellationToken)

Fails every interrupt a run still has pending.

Parameters

runId
The run that stopped.
failureCode
Why it stopped.
cancellationToken
The caller's token.

MethodRecordToolCallAsync(string, CancellationToken)

Counts one tool call against the run when it is attempted, which is what the cap spends.

Assistant.IMemoryStore

The assistant's owner-scoped memory, as the run and the tools use it.
Every method takes the owner and every statement filters on it, so a wrong owner and a missing memory answer the same way and a probe cannot tell them apart. The owner never comes from the model (`assistant-memory-is-the-owners`).

MethodRecallAsync(string owner, string queryTerms, int limit, CancellationToken cancellationToken)

The owner's memories that match an FTS5 expression, best match first.

Parameters

owner
The account whose memories are searched.
queryTerms
The expression Terms built.
limit
The most candidates to return.
cancellationToken
Cancels the query.

MethodStickyAsync(string owner, long conversationId, CancellationToken cancellationToken)

The owner's memories this conversation has already used, most recently used first.

Parameters

owner
The account whose memories are read.
conversationId
The conversation whose recall is sticky.
cancellationToken
Cancels the query.

MethodPinnedAsync(string owner, CancellationToken cancellationToken)

The owner's pinned memories, newest change first.

Parameters

owner
The account whose memories are read.
cancellationToken
Cancels the query.

MethodListAsync(string owner, CancellationToken cancellationToken)

Every memory the owner holds, newest change first, for the owner's own page.

Parameters

owner
The account whose memories are read.
cancellationToken
Cancels the query.

MethodGetAsync(string owner, long id, CancellationToken cancellationToken)

One memory the owner holds, or null when there is no such memory for them.

Parameters

owner
The account whose memory is read.
id
The memory's id.
cancellationToken
Cancels the query.

MethodEditAsync(string owner, long id, int expectedVersion, MemoryKind kind, string content, bool pinned, CancellationToken cancellationToken)

The owner's edit of a memory: its content, its kind and its pin.
This is the only write that can set Pinned. The assistant's UpdateAsync has no such argument, so a model cannot pin a memory by any path (`assistant-memory-page`).

Parameters

owner
The account the memory belongs to.
id
The memory to change.
expectedVersion
The version the page was rendered from; a stale one is refused.
kind
The kind the owner chose.
content
The note as the owner wrote it.
pinned
Whether the owner pinned it.
cancellationToken
Cancels the write.

MethodRememberAsync(string owner, MemoryKind kind, string content, Assistant.MemorySource source, CancellationToken cancellationToken)

Stores a memory, or returns the row that already says the same thing.

Parameters

owner
The account the memory belongs to.
kind
What kind of note it is.
content
The note, as the model wrote it.
source
The conversation and run that wrote it.
cancellationToken
Cancels the write.

MethodUpdateAsync(string owner, long id, int expectedVersion, string content, Assistant.MemorySource source, CancellationToken cancellationToken)

Replaces a memory's content, keeping the version it replaced as history.

Parameters

owner
The account the memory belongs to.
id
The memory to change.
expectedVersion
The version the caller read; a stale one is refused.
content
The new note.
source
The conversation and run that made the edit.
cancellationToken
Cancels the write.

MethodForgetAsync(string owner, long id, CancellationToken cancellationToken)

Deletes a memory and its history.

Parameters

owner
The account the memory belongs to.
id
The memory to forget.
cancellationToken
Cancels the delete.

Returns

Whether a memory was there to forget.

MethodTouchAsync(string owner, IReadOnlyList<long> ids, long conversationId, CancellationToken cancellationToken)

Records that a run used these memories.

Parameters

owner
The account the memories belong to.
ids
The memories the run was given.
conversationId
The conversation that used them.
cancellationToken
Cancels the update.

MethodCountAsync(string owner, CancellationToken cancellationToken)

How many memories the owner holds, for the cap the page shows.

Parameters

owner
The account to count.
cancellationToken
Cancels the count.

MethodClearProvenanceAsync(long conversationId, CancellationToken cancellationToken)

Drops the provenance of the memories a deleted conversation wrote, keeping them.

Parameters

conversationId
The conversation being deleted.
cancellationToken
Cancels the update.

Returns

How many memories lost their provenance.

MethodDeleteForOwnerAsync(string owner, CancellationToken cancellationToken)

Deletes every memory an account holds, which is what removing the account does.

Parameters

owner
The account being removed.
cancellationToken
Cancels the delete.

Returns

How many memories were removed.

Assistant.IPageStoreReader

The page store as everything that reads it sees it.
One seam, so the assistant's tools and its virtual shell cannot decide differently what the store contains: which keys are reserved, which tombstones are visible, what order keys come in, what a scope means and what a revision is. Writes are deliberately not here; they stay with the saver.

MethodTreeAsync(bool includeDeleted, CancellationToken cancellationToken)

Every node of the tree, in ordinal order, with tombstones when they are asked for.

Parameters

includeDeleted
Whether a key that is only a tombstone is a node in the answer.
cancellationToken
The run's token.

MethodSourcesAsync(IReadOnlyList<PageScope> scopes, CancellationToken cancellationToken)

What the pages and shell records inside the scopes hold, in key order.

Parameters

scopes
The paths to read, each saying whether it is itself read and whether it descends.
cancellationToken
The run's token.

MethodReadAsync(PagePath path, CancellationToken cancellationToken)

What one key holds, or null when nothing is stored at it.

Parameters

path
The node to read.
cancellationToken
The run's token.

MethodHistoryAsync(PagePath path, CancellationToken cancellationToken)

A page's head and every revision it retains.

Parameters

path
The page to read the history of; a tombstone's history is answered too.
cancellationToken
The run's token.

MethodRevisionAsync(PagePath path, string hash, CancellationToken cancellationToken)

The revision with that hash, only when it is a revision of this page.

Parameters

path
The page the revision must belong to.
hash
The canonical hash a listing or a form carried.
cancellationToken
The run's token.

Assistant.IProviderModelsClient

The model list read, as the sampler and the run ask for it.

MethodGetAsync(CancellationToken cancellationToken)

Reads the configured model's window and output limit.

Parameters

cancellationToken
Cancelled when the host stops.

Returns

What the provider answered, with the reason when it carries no figures.

Assistant.InterruptPayloads

Reads and writes the two halves of an interrupt, so no caller hand-builds one.
The shapes live here rather than on the record because the record is deliberately opaque: the store never parses a request or a resolution, which is what lets a new kind arrive with no schema change. A row this build cannot read is treated as absent rather than as an error, because a transcript is more useful than a stack trace.

MethodWrite(object payload)

The stored form of a request or a resolution.

Parameters

payload
The value to store.

MethodApproval(string requestJson)

The approval a request describes, or null when it is not one this build understands.

Parameters

requestJson
The stored request.

MethodContinuation(string requestJson)

The continuation a request describes, or null when it is not one this build understands.

Parameters

requestJson
The stored request.

MethodResolution(string resolutionJson)

The decision a resolution records, or null when it is not one this build understands.

Parameters

resolutionJson
The stored resolution.

Assistant.InterruptResolutionResult

How a write against a pending interrupt ended.

FieldResolved

The record was resolved and the run is going again.

FieldNotFound

No interrupt with that run and owner exists, or the conversation is not the owner's.

FieldConflict

The record or its run has moved on, so the form that arrived is stale.

Assistant.LineMatch

One line of a page that a search matched.

MethodLineMatch(PagePath Path, int Line, string Text)

One line of a page that a search matched.

Parameters

Path
The key the line was read from.
Line
The 1-based line of that key.
Text
The line itself, without its line break.

PropertyPath

The key the line was read from.

PropertyLine

The 1-based line of that key.

PropertyText

The line itself, without its line break.

Assistant.LineMatches

What a scan found, and whether a limit left something out.

MethodLineMatches(IReadOnlyList<Assistant.LineMatch> Matches, bool Truncated)

What a scan found, and whether a limit left something out.

Parameters

Matches
The matching lines, in key then line order.
Truncated
Whether a limit stopped the scan before the sources ran out.

PropertyMatches

The matching lines, in key then line order.

PropertyTruncated

Whether a limit stopped the scan before the sources ran out.

Assistant.MemoryEdit

A version a memory was replaced from, kept so an update leaves a trail.
The key is the memory and the version that was replaced, and the foreign key to the head is real: history has no meaning once its memory is forgotten, so a forget takes the trail with it.

PropertyMemoryId

The memory this version belonged to.

PropertyVersion

The version number the replaced content carried.

PropertyKind

The kind as it was.

PropertyContent

The content as it was.

PropertyEditedAt

When it was replaced.

PropertySourceConversationId

The conversation the edit was made in, or null when the assistant made it in a run whose conversation has since been deleted.

Assistant.MemoryEntry

One memory: the head row, which is the current version and the only one recall reads.
The owner is the security boundary: every statement filters on it. Provenance is deliberately not a foreign key, because a memory outlives the conversation that produced it (`assistant-memory-is-the-owners`).

PropertyId

The row's id, which the model names in update_memory and forget_memory.

PropertyOwner

The account the memory belongs to.

PropertyKind

The kind's stored name, one of preference, fact, feedback or reference.

PropertyContent

The normalised note.

PropertyVersion

The version an update has to carry to be accepted.

PropertyPinned

The owner's "always use this". The assistant cannot set it.

PropertySourceConversationId

The conversation that wrote this version, or null once that conversation is deleted.

PropertySourceRunId

The run that wrote this version, or null once that conversation is deleted.

PropertyCreatedAt

When the memory was first written.

PropertyUpdatedAt

When this version was written.

PropertyLastRecalledAt

When a run last recalled it.

PropertyLastRecalledConversationId

The conversation that last recalled it, which is the stickiness recall uses.

PropertyRecallCount

How many runs have recalled it.

Assistant.MemorySource

Where a memory's current version came from: the conversation and the run that wrote it.
A record of both, so a caller cannot pass one and forget the other, and so the owner's page can link back to the turn that wrote a memory while that conversation exists.

MethodMemorySource(long ConversationId, string RunId)

Where a memory's current version came from: the conversation and the run that wrote it.
A record of both, so a caller cannot pass one and forget the other, and so the owner's page can link back to the turn that wrote a memory while that conversation exists.

Parameters

ConversationId
The conversation the write happened in.
RunId
The run that made the call.

PropertyConversationId

The conversation the write happened in.

PropertyRunId

The run that made the call.

Assistant.MemoryWriteResult

What a memory write did: stored a memory, or refused with something the model can act on.

MethodMemoryWriteResult(bool IsSuccess, MemoryCandidate Memory, string Error)

What a memory write did: stored a memory, or refused with something the model can act on.

Parameters

IsSuccess
Whether the store changed.
Memory
The memory as it now stands, when the write succeeded.
Error
A sentence the model can act on, when it did not.

PropertyIsSuccess

Whether the store changed.

PropertyMemory

The memory as it now stands, when the write succeeded.

PropertyError

A sentence the model can act on, when it did not.

MethodStored(MemoryCandidate memory)

A write that left the store holding memory.

Parameters

memory
The memory as it now stands, which for a duplicate is the row already there rather than a new one.

MethodRefused(string error)

A write that changed nothing, and why.

Parameters

error
The sentence the tool result carries.

Assistant.Message

One stored message of a conversation, including its tool calls and their results.

MethodToChatMessage()

This message as the provider would see it, which is what the budgeting rules measure.

Assistant.MessageInput

A message to append to a conversation.

MethodMessageInput(string, string, string, string, string, string, string)

A message to append to a conversation.

Assistant.ModelWindowRead

What the provider's model list says about the configured model.

MethodModelWindowRead(long? ContextWindow, int? MaximumOutputTokens, Assistant.ModelWindowReason Reason)

What the provider's model list says about the configured model.

Parameters

ContextWindow
The window the model accepts, in tokens, when it was reported.
MaximumOutputTokens
The largest reply the model accepts, in tokens, when it was reported.
Reason
Whether the figures are there, and why not when they are not.

PropertyContextWindow

The window the model accepts, in tokens, when it was reported.

PropertyMaximumOutputTokens

The largest reply the model accepts, in tokens, when it was reported.

PropertyReason

Whether the figures are there, and why not when they are not.

PropertyUnknown

The state before anything has been read.

PropertyIsAvailable

Whether both figures were reported.

MethodOk(long, int)

A read that found both figures.

MethodFailed(Assistant.ModelWindowReason)

A read that produced no window, with the reason.

MethodSameAs(Assistant.ModelWindowRead other)

Whether this answer names the same figures as other.

Parameters

other
The read to compare with.

Returns

True when both carry the same window and output limit.

Assistant.ModelWindowReason

Why the provider has, or has not, told this host what the configured model's limits are.

FieldOk

The provider answered with the model's window and output limit.

FieldModelMissing

The provider answered, and the configured model is not in its list.

FieldIncomplete

The provider answered, and the entry omits the window or the output limit.

FieldTimeout

The provider did not answer in time.

FieldUnreachable

The provider could not be reached.

FieldError

The provider answered with an error status.

FieldInvalid

The provider's answer was not the model list.

FieldUnknown

Nothing has been read yet.

Assistant.ModelWindowSampler

Reads the provider's model list and keeps the budget the answer supports.
The read happens once at startup and again when a request is rejected for length, because that rejection is the one signal that the cached window is stale. It is never fatal on its own: the assistant is one feature, and a provider that is down must not take the page server with it. The one answer that is fatal is the provider saying the configured model does not exist, because that is authoritative and the owner should hear it at deploy time rather than from a failed run.

MethodModelWindowSampler(IServiceScopeFactory, Assistant.ModelWindowSource, Assistant.AssistantOptions, ILogger<Assistant.ModelWindowSampler>)

Reads the provider's model list and keeps the budget the answer supports.
The read happens once at startup and again when a request is rejected for length, because that rejection is the one signal that the cached window is stale. It is never fatal on its own: the assistant is one feature, and a provider that is down must not take the page server with it. The one answer that is fatal is the provider saying the configured model does not exist, because that is authoritative and the owner should hear it at deploy time rather than from a failed run.

PropertyBudget

The budget the last read supports, or null when there is no window.

PropertyRead

The last read.

MethodRefreshAsync(CancellationToken cancellationToken)

Reads the model list and records what it supports.

Parameters

cancellationToken
Cancelled when the host stops.

Returns

What the provider answered.

Exceptions

The provider says the configured model does not exist.

Assistant.ModelWindowSource

The model window the last read found, and the content budget it resolves to.
One immutable value for the process, so a step never waits on a read. The budget is resolved when the read lands rather than on every request; a run that has no budget refuses rather than guessing (assistant-the-budget-is-window-minus-reply).

PropertyRead

The last read.

PropertyBudget

The content budget the last read supports, or null when there is no window.

MethodRecord(Assistant.ModelWindowRead read, int minimumOutputTokens)

Records a read, resolving the budget it supports.

Parameters

read
What the provider answered.
minimumOutputTokens
The configured floor under a reply.

Exceptions

ArgumentOutOfRangeException
The floor leaves too little of the window for the prompt.

MethodFixed(ContextBudget budget)

A source fixed to one budget, for a test that is not about the provider.

Parameters

budget
The budget every read answers with.

Assistant.OpenAiChatCompletionClient

Streams completions from an OpenAI-compatible chat-completions endpoint.

MethodOpenAiChatCompletionClient(HttpClient, Assistant.AssistantOptions, ILogger<Assistant.OpenAiChatCompletionClient>)

Streams completions from an OpenAI-compatible chat-completions endpoint.

MethodNamesContextLength(string body)

Whether a provider's rejection names the context length as its cause.
The body is parsed and then dropped: the message is the provider's text and is never logged or shown, so only the fact that it named the window survives.

Parameters

body
The provider's error body.

Returns

True when the error's code, type or message says the request was too long.

Assistant.OwnerInterrupt

One time a run stopped and asked its owner for something.
The run waits on one thing at a time, so the run's id is the key: a second interrupt for a run that already has one is a defect in the caller, not a second question. The request and the resolution are the host's own JSON and the store never reads inside them, which is what lets a new kind of question be added without a column, a table or a migration.

PropertyToolCallId

The call the wait belongs to, or null when the wait is not about a tool call.

PropertyRequestJson

What the owner is shown, as Assistant.InterruptPayloads writes it.

PropertyResolutionJson

What the owner chose or typed, once they have.

Assistant.OwnerInterruptCoordinator

Wakes the worker of a run whose owner has resolved its interrupt.
The run's worker holds the loop's state while it waits, so the signal only has to wake it: the resolution is read from the store, which is where the endpoint put it. A run waits on one thing at a time, so the run id is the whole key and a second wait for the same run is a defect rather than a separate wait to track.

MethodWaitAsync(string runId, CancellationToken cancellationToken)

Waits for the owner's resolution of this run's interrupt.

Parameters

runId
The run whose interrupt is pending.
cancellationToken
The run's token.

MethodSignal(string runId)

Wakes the run's worker, if it is waiting.

Parameters

runId
The run whose interrupt was resolved.

Returns

Whether a waiter was woken.

Assistant.OwnerInterruptKind

The kinds of thing a run can stop to ask its owner.

FieldApproval

A flagged tool call waits for the owner to allow or refuse it before it runs.

FieldContinuation

A run that spent a budget waits for the owner to tell it to carry on.

Assistant.OwnerInterruptStatus

The states an interrupt can be in.
One status per state rather than one per resolution: what the owner decided lives in the resolution, so every kind shares the same three words and a new kind does not invent a vocabulary.

Assistant.OwnerResolution

What the owner decided, for the kinds whose answer is a choice.

MethodOwnerResolution(string Decision)

What the owner decided, for the kinds whose answer is a choice.

Parameters

Decision
The word the kind's form asked for.

PropertyDecision

The word the kind's form asked for.

Assistant.PageAuthorPrompt

The system prompt and worked examples that teach the model to write a page.

Assistant.PageHistory

A page's history: its head, and every revision it retains.

MethodPageHistory(bool Exists, bool IsDeleted, IReadOnlyList<Pages.PageRevisionSummary> Revisions)

A page's history: its head, and every revision it retains.

Parameters

Exists
Whether a head exists, a tombstone's included.
IsDeleted
Whether the head is a tombstone.
Revisions
The retained revisions, newest first.

PropertyExists

Whether a head exists, a tombstone's included.

PropertyIsDeleted

Whether the head is a tombstone.

PropertyRevisions

The retained revisions, newest first.

PropertyMissing

The answer for a key no page has ever been saved at.

Assistant.PageNode

One node of the page store as a reader sees it: a key, a folder above one, or a route.
The node carries facts rather than words: the permission column and the compile state are formatted by whoever shows them, with Pages.PageMode and Pages.PageImageStatus, so a tool and an applet cannot describe one page differently.

MethodPageNode(PagePath Path, bool IsFolder, bool IsPage, bool IsShellFile, bool IsDeleted, bool CanWrite, Pages.PageImageState? State)

One node of the page store as a reader sees it: a key, a folder above one, or a route.
The node carries facts rather than words: the permission column and the compile state are formatted by whoever shows them, with Pages.PageMode and Pages.PageImageStatus, so a tool and an applet cannot describe one page differently.

Parameters

Path
The canonical key.
IsFolder
Whether any key lives beneath it, so that it can be listed.
IsPage
Whether a page or a shell file is stored at the key itself.
IsShellFile
Whether the site's own routes answer the key, so no page is stored there.
IsDeleted
Whether the key is a tombstone that still has its history.
CanWrite
Whether a save at the key would be accepted, which is the permission column.
State
What the page's current revision compiled to, or null when the key holds no page.

PropertyPath

The canonical key.

PropertyIsFolder

Whether any key lives beneath it, so that it can be listed.

PropertyIsPage

Whether a page or a shell file is stored at the key itself.

PropertyIsShellFile

Whether the site's own routes answer the key, so no page is stored there.

PropertyIsDeleted

Whether the key is a tombstone that still has its history.

PropertyCanWrite

Whether a save at the key would be accepted, which is the permission column.

PropertyState

What the page's current revision compiled to, or null when the key holds no page.

Assistant.PagePathPolicy

Which pages the assistant may read, and which it may write.
One kind of key is read-only: a shell file, a key the site's own routes answer — the shell's route table, which is also the reserved list. It is readable, because the tools describe what the route does, and it is never a stored page. Everything else is a page the assistant may list, read and write, subject to Assistant:WritablePathPrefix.

PropertyReserved

The shell files: every key the site's own routes answer.

MethodValidatePrefix(string prefixText)

Validates an optional prefix, which only has to be an addressable path.

Parameters

prefixText
The prefix the model asked for, or null for none.

MethodIsReserved(PagePath)

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

MethodCanWrite(PagePath)

Whether a save at this key would be accepted, which is what the permission column says.

MethodShadowedBy(PagePath)

The shell file that shadows this key, when the key itself is not the reserved one.

Assistant.PageRead

What one key holds.

MethodPageRead(PagePath Path, bool IsShellFile, bool CanWrite, Pages.PageImageState? State, string Text, Pages.PageTemplate Page)

What one key holds.

Parameters

Path
The canonical key.
IsShellFile
Whether the site's own routes answer the key.
CanWrite
Whether a save at the key would be accepted.
State
What the page's current revision compiled to, or null for a shell file.
Text
The page's stored template, or the shell file's record of what the route does.
Page
The page and the image built from it, or null when the key is a shell file.

PropertyPath

The canonical key.

PropertyIsShellFile

Whether the site's own routes answer the key.

PropertyCanWrite

Whether a save at the key would be accepted.

PropertyState

What the page's current revision compiled to, or null for a shell file.

PropertyText

The page's stored template, or the shell file's record of what the route does.

PropertyPage

The page and the image built from it, or null when the key is a shell file.

Assistant.PageSourceSearch

One scan of page sources, shared by the search tool and the shell's grep.

The walk is the same in both: sources in key order, each split into lines by the caller's own rule, each line tested by the caller's own predicate. Only the projection and the wording differ, and they stay with the caller.

The two line rules are deliberately not one. PageToolData.TemplateSourceLines counts physical template lines, which are the lines read_page and edit_page name; ShellText.Split counts terminated lines, as POSIX does. Merging them would make an edit address the wrong line in a page whose source does not end with a newline.

MethodFind(IReadOnlyList<Assistant.PageRead> sources, Func<string, string[]> lines, Func<string, bool> matches, int limit)

Scans the sources for matching lines.

Parameters

sources
The sources to read, already in key order.
lines
The caller's line rule for a source's text.
matches
The caller's test for one line.
limit
How many matches the answer may carry.

Returns

The matches found before the limit, and whether a further match existed. The scan stops one match past the limit rather than guessing from the count, so "there are more" is an observation.

Assistant.PageStoreReader

The store behind the tools and the shell, over the editor and the path policy.
Constructed where it is used, the way the shell's view was: it holds no state beyond the two singletons it reads through.

MethodPageStoreReader(Editor.PageEditor pages, Assistant.PagePathPolicy paths)

The store behind the tools and the shell, over the editor and the path policy.
Constructed where it is used, the way the shell's view was: it holds no state beyond the two singletons it reads through.

Parameters

pages
The editor, which reads pages, histories and the running build.
paths
The policy, which says what exists and what may be written.

MethodTreeAsync(bool, CancellationToken)

Every node of the tree, in ordinal order, with tombstones when they are asked for.

Inherited from Assistant.IPageStoreReader.TreeAsync.

Parameters

includeDeleted
Whether a key that is only a tombstone is a node in the answer.
cancellationToken
The run's token.

MethodSourcesAsync(IReadOnlyList<PageScope>, CancellationToken)

What the pages and shell records inside the scopes hold, in key order.

Inherited from Assistant.IPageStoreReader.SourcesAsync.

Parameters

scopes
The paths to read, each saying whether it is itself read and whether it descends.
cancellationToken
The run's token.

MethodReadAsync(PagePath, CancellationToken)

What one key holds, or null when nothing is stored at it.

Inherited from Assistant.IPageStoreReader.ReadAsync.

Parameters

path
The node to read.
cancellationToken
The run's token.

MethodHistoryAsync(PagePath, CancellationToken)

A page's head and every revision it retains.

Inherited from Assistant.IPageStoreReader.HistoryAsync.

Parameters

path
The page to read the history of; a tombstone's history is answered too.
cancellationToken
The run's token.

MethodRevisionAsync(PagePath, string, CancellationToken)

The revision with that hash, only when it is a revision of this page.

Inherited from Assistant.IPageStoreReader.RevisionAsync.

Parameters

path
The page the revision must belong to.
hash
The canonical hash a listing or a form carried.
cancellationToken
The run's token.

Assistant.PageToolExecutor

The seam the run calls through: finds the tool, validates its arguments, and gives it the call's services.
Orchestration only. What a tool is and what it does is on its own type in Tools; this class opens the per-call scope, builds the services a tool may use and hands the validated arguments over.

MethodPageToolExecutor(IServiceScopeFactory, Assistant.PagePathPolicy, Assistant.AssistantOptions, Assistant.ModelWindowSource, Assistant.AssistantMetrics, Assistant.IAssistantFetcher)

The seam the run calls through: finds the tool, validates its arguments, and gives it the call's services.
Orchestration only. What a tool is and what it does is on its own type in Tools; this class opens the per-call scope, builds the services a tool may use and hands the validated arguments over.

PropertyDefinitions

What the model is offered, in declaration order.

MethodChangesPages(string toolName)

Whether the named tool changes a stored page when it succeeds.

Parameters

toolName
The tool the model called, as the transcript stored it.

MethodRefuseBeforeApproval(string name, string argumentsJson)

The refusal the path policy gives a mutating call, or null when the call may run.
The approval gate asks this before it prompts. An approval the policy has already refused is one the owner could only deny, so it is not worth their attention. An unknown tool, a tool that writes nothing or names no path, bad arguments and a permitted path all answer null, because PageToolExecutor.ExecuteAsync owns those refusals and the owner may still want to see the call. fetch is approval-gated and has no path, so its URL is the prompt's to show.

Parameters

name
The tool the model called.
argumentsJson
Its complete arguments, as validated.

Assistant.PathValidationResult

A validated page path, or why the assistant may not use the one it asked for.

MethodPathValidationResult(PagePath, string)

A validated page path, or why the assistant may not use the one it asked for.

Assistant.ProviderException

A provider failure that carries a message safe to show and a stable code for metrics.

MethodProviderException(string, string, Exception)

A provider failure that carries a message safe to show and a stable code for metrics.

FieldContextWindowMismatch

The provider rejected the request because the prompt and the reply exceed the window.
It is its own code because it is the one rejection that says the cached window is stale, so the run reads the model list again and sends the step once more rather than failing the run.

Assistant.ProviderModelsClient

Reads the provider's model list, which is where a model's limits are written down.
Every failure — an error status, a timeout, an unreachable host, a body that is not the model list — is a reason rather than an exception, so a provider that is down at startup costs the assistant its budget and nothing else. The provider's body is never logged: the reason is the whole diagnosis, and the model list is not this host's to publish.

MethodProviderModelsClient(HttpClient, Assistant.AssistantOptions)

Reads the provider's model list, which is where a model's limits are written down.
Every failure — an error status, a timeout, an unreachable host, a body that is not the model list — is a reason rather than an exception, so a provider that is down at startup costs the assistant its budget and nothing else. The provider's body is never logged: the reason is the whole diagnosis, and the model list is not this host's to publish.

MethodGetAsync(CancellationToken)

Reads the configured model's window and output limit.

Inherited from Assistant.IProviderModelsClient.GetAsync.

Parameters

cancellationToken
Cancelled when the host stops.

Returns

What the provider answered, with the reason when it carries no figures.

MethodParse(string body, string model)

Finds the configured model's figures in the provider's answer.
The provider says either figure "may be omitted when the information is not available for that model", and guessing one is what the budget's decision refuses, so an omitted figure is a missing window rather than a default. A model absent from the list is a different answer: the provider is authoritative, and the owner hears about it at startup.

Parameters

body
The JSON the provider answered with.
model
The configured model name.

Returns

The window and output limit, or the reason there is none.

Assistant.QueuedRun

A run waiting for a worker.

MethodQueuedRun(long, string, string)

A run waiting for a worker.

Assistant.Run

One stored run of a conversation: its status, model, usage and any error.

PropertyPromptTokens

Every step's prompt tokens added together.

PropertyCompletionTokens

Every step's completion tokens added together.

PropertyCachedTokens

Every step's cache-hit prompt tokens added together.

PropertyReasoningTokens

Every step's reasoning tokens added together.

PropertyOutputTokens

The most recent step's completion tokens, which the completion budget counts.

PropertyEstimatedTokens

The most recent request's estimated prompt tokens, which the estimate's error is measured from.

PropertyMaxTokens

The most recent request's max_tokens, which is the allowance that step had.

PropertyRequestBytes

The UTF-8 bytes of the last request this run sent, for calibrating the token estimate.

PropertyLastPromptTokens

The last request's provider-reported prompt tokens, for calibrating the token estimate.

PropertyStepLimit

The run's step budget, or null while it is the configured one.
A continuation adds one window to the budget it ran out of, so this is what the page shows and what the processor resumes with.

PropertyToolCallLimit

The run's tool-call budget, or null while it is the configured one.

MethodToUsage()

The stored totals as the value the page and the run publish.

Assistant.RunBudget

The run budgets a run can run out of, as the run and the page name them.
The first two are the budget rows the page draws, so their names are page-facing; the third has no row of its own because it bounds one step rather than the run.

FieldSteps

The run has taken all the steps its budget allows.

FieldToolCalls

The run has made all the tool calls its budget allows.

FieldToolCallsPerStep

One step asked for more tool calls than a single step may make.

MethodSentence(string budget, int limit, int window)

The sentence that says which budget ran out, and what continuing buys.
One sentence, written by the host, so the live card and the reloaded one cannot say different things about the same pause.

Parameters

budget
One of the budget constants.
limit
The limit the run reached.
window
How much a continuation adds.

Assistant.RunEvent

One journaled event of a run, as the assistant page replays it.

MethodRunEvent(string, long, string, string)

One journaled event of a run, as the assistant page replays it.

Assistant.RunJournalCleanupService

Drops expired run journals on a timer.

MethodRunJournalCleanupService(Assistant.RunRegistry, ILogger<Assistant.RunJournalCleanupService>)

Drops expired run journals on a timer.

Assistant.RunProcessor

Runs one queued assistant run to completion, streaming its events and executing its tools.

MethodRunProcessor(IServiceScopeFactory, Assistant.IChatCompletionClient, Assistant.PageToolExecutor, Assistant.RunRegistry, Assistant.OwnerInterruptCoordinator, Assistant.AssistantMetrics, Assistant.AssistantOptions, Assistant.ModelWindowSampler, Users.IUserStore, Authentication.ViewTokenStore, ILogger<Assistant.RunProcessor>)

Runs one queued assistant run to completion, streaming its events and executing its tools.

MethodWaitAsync(Assistant.QueuedRun, Assistant.RunStream, int, string, string, object, CancellationToken)

Stops the run until its owner resolves the interrupt this opens.

Returns

The resolved interrupt, or null when the run could not be stopped for the ask.

Assistant.RunQueue

The bounded queue of runs waiting for a worker.
A run the queue cannot hold is refused rather than queued, and the worker runs one at a time because there is one compile slot behind it.

MethodRunQueue(Assistant.AssistantOptions)

The bounded queue of runs waiting for a worker.
A run the queue cannot hold is refused rather than queued, and the worker runs one at a time because there is one compile slot behind it.

Assistant.RunRegistry

The live run journals, by run id and by conversation.

MethodRunRegistry(Assistant.AssistantOptions, TimeProvider)

The live run journals, by run id and by conversation.

Assistant.RunStartResult

The outcome of asking to start a run.

MethodRunStartResult(Assistant.RunStartStatus, string, long?)

The outcome of asking to start a run.

Assistant.RunStartStatus

Why a request to start a run did or did not start one.

Assistant.RunStatus

The statuses a run is stored in, named once so the queries cannot drift apart.
Every status is here because more than one place has to agree on it: the active-run queries, the recovery sweep and the processor all decide whether a run is still going. Only the partial index's filter spells the active ones out again, because a schema definition is written in the migration rather than read from code.

FieldAwaitingOwner

The run is stopped and the owner's answer is what moves it on.

MethodIsActive(string status)

Whether a run in this status is still the conversation's active run.

Parameters

status
A stored status.

Assistant.RunStream

One run's journal of events and its live subscribers.

MethodRunStream(string, Assistant.AssistantOptions, TimeProvider)

One run's journal of events and its live subscribers.

MethodDispose()

Releases the stop source once nothing can still be waiting on the run.

Assistant.RunWorker

Reads the run queue and runs jobs within the configured concurrency.

MethodRunWorker(Assistant.RunQueue, IServiceScopeFactory, Assistant.AssistantOptions, ILogger<Assistant.RunWorker>)

Reads the run queue and runs jobs within the configured concurrency.

Assistant.SqliteConversationStore

The SQLite-backed conversation store.

MethodSqliteConversationStore(Storage.StorageDbContext, TimeProvider, ILogger<Assistant.SqliteConversationStore>)

The SQLite-backed conversation store.

Assistant.SqliteMemoryStore

The SQLite-backed memory store: two tables, one FTS5 index, every statement owner-scoped.
The writes that have to be atomic are atomic in SQLite rather than in this class: the cap and the insert share a transaction, and so do the version check, the history row and the new head. Recall spends its money on the FTS5 query and filters the owner beside it, so an index search never sees another account's text.

MethodSqliteMemoryStore(Storage.StorageDbContext, Assistant.AssistantOptions, TimeProvider)

The SQLite-backed memory store: two tables, one FTS5 index, every statement owner-scoped.
The writes that have to be atomic are atomic in SQLite rather than in this class: the cap and the insert share a transaction, and so do the version check, the history row and the new head. Recall spends its money on the FTS5 query and filters the owner beside it, so an index search never sees another account's text.

Assistant.ToolContext

Who a tool call is for: the owner, the conversation and the run.
Memory is the first tool family that belongs to a person rather than to the site, so the executor is told who is calling instead of reading it from the model's arguments. The owner comes from the signed-in conversation and there is no path by which a model-supplied string becomes one (`assistant-memory-is-the-owners`).

MethodToolContext(string Owner, long ConversationId, string RunId)

Who a tool call is for: the owner, the conversation and the run.
Memory is the first tool family that belongs to a person rather than to the site, so the executor is told who is calling instead of reading it from the model's arguments. The owner comes from the signed-in conversation and there is no path by which a model-supplied string becomes one (`assistant-memory-is-the-owners`).

Parameters

Owner
The account the run belongs to.
ConversationId
The conversation the run is in.
RunId
The run making the call.

PropertyOwner

The account the run belongs to.

PropertyConversationId

The conversation the run is in.

PropertyRunId

The run making the call.

PropertySource

Where a memory written by this call came from.

Assistant.ToolExecutionResult

What one tool call produced, as the model receives it.

MethodToolExecutionResult(bool, string, string)

What one tool call produced, as the model receives it.

Assistant.Shell

Assistant.Shell.IShellOutput

Where an applet writes its answer.
An applet writes; it does not return a string. That is what will let a pipeline put the next command's input where the tool result goes without an applet knowing the difference.

PropertyMatchLimit

How many matches a search may show before it has to say it stopped.

PropertyListingLimit

How many entries a listing may show before it has to say it stopped.

PropertyTruncated

Whether the answer is missing something, because a limit stopped it.

PropertyText

The answer, without a trailing line break.

MethodLine(string text)

Writes one line.

Parameters

text
The line, without its line break.

MethodRaw(string text)

Writes text as it stands, ending it with a line break unless it has one.

Parameters

text
The text.

MethodNote(string note)

Writes a bracketed note that says something about the answer without cutting it short.

Parameters

note
The note, without its brackets.

MethodStopped(string note)

Writes the note that says a limit was reached, and marks the answer truncated.

Parameters

note
The note, without its brackets.

Assistant.Shell.ShellApplet

One command of the virtual shell: its usage, its syntax and its behaviour, in one place.
An applet is the whole of a command, the way a BusyBox applet is: its name, the usage line help prints, the syntax the kernel validates against, the notes help adds when it is asked about it, and the code that runs it. Nothing outside an applet knows what its options mean, and adding a command is adding a file and a row in the registry.

PropertyName

The command's word.

PropertyUsage

The whole form it is called in, options and operands included.

PropertyDescription

One line saying what it does, which help prints after the usage.

PropertyNotes

The syntax that one line cannot carry, when there is some.

PropertySyntax

What the kernel accepts on its command line.

MethodRunAsync(ShellCommandLine line, Assistant.Shell.ShellContext context, CancellationToken cancellationToken)

Runs the command.

Parameters

line
The parsed command line.
context
The shared tools: the expanded paths, the store, the output and the registry.
cancellationToken
The run's token.

Assistant.Shell.ShellContext

What an applet is given for one run.

MethodShellContext(ShellCommandLine line, IReadOnlyList<Assistant.PageNode> paths, Assistant.IPageStoreReader store, Assistant.Shell.IShellOutput output, Assistant.Shell.ShellRegistry registry, Assistant.AssistantOptions options)

What an applet is given for one run.

Parameters

line
The parsed command line.
paths
The paths its operands named, expanded and validated.
store
The one read seam over the page store.
output
Where the answer is written.
registry
The applets, which help reads.
options
The assistant's configured limits, for the defaults an applet uses.

PropertyLine

The parsed command line.

PropertyPaths

The paths the operands named, in the order they were written.

PropertyStore

The one read seam over the page store.

PropertyOutput

Where the answer is written.

PropertyRegistry

The applets, which help reads.

PropertyOptions

The assistant's configured limits.

Assistant.Shell.ShellExpansion

Turns a command's operands into the nodes they name.
One stage, for every command: the applet declares what kind of operand it takes and this decides what the words mean. A path is validated and looked up, a prefix may be a folder, a text operand is left alone, and a word that names nothing is a refusal — never an empty answer that looks like a command which found nothing.

MethodShellExpansion(Assistant.PagePathPolicy paths)

Turns a command's operands into the nodes they name.
One stage, for every command: the applet declares what kind of operand it takes and this decides what the words mean. A path is validated and looked up, a prefix may be a folder, a text operand is left alone, and a word that names nothing is a refusal — never an empty answer that looks like a command which found nothing.

Parameters

paths
The policy, which says what a key may be.

MethodExpandAsync(IReadOnlyList<ShellArgument> arguments, Assistant.IPageStoreReader store, CancellationToken cancellationToken)

The nodes the operands name, or the refusal that says why one does not name any.

Parameters

arguments
The operands, with the kind the applet declared for each.
store
The store to resolve them against.
cancellationToken
The run's token.

Assistant.Shell.ShellOutcome

What the kernel has to say about a line, in the shape the tool result wants.

MethodShellOutcome(bool IsSuccess, string Output, bool Truncated, string Summary, string Error)

What the kernel has to say about a line, in the shape the tool result wants.

Parameters

IsSuccess
Whether the command ran.
Output
What it wrote, when it ran.
Truncated
Whether a limit or the result budget left something out.
Summary
One line for the tool result's summary.
Error
The refusal, when it failed.

PropertyIsSuccess

Whether the command ran.

PropertyOutput

What it wrote, when it ran.

PropertyTruncated

Whether a limit or the result budget left something out.

PropertySummary

One line for the tool result's summary.

PropertyError

The refusal, when it failed.

MethodAnswered(string output, bool truncated, string summary)

An answer.

Parameters

output
What the command wrote.
truncated
Whether something was left out.
summary
One line for the tool result's summary.

MethodRefused(string error, string summary)

A refusal.

Parameters

error
The refusal.
summary
One line for the tool result's summary.

Assistant.Shell.ShellOutput

An answer being written: lines in order, and whether a limit stopped it.

PropertyMatchLimit

How many matches a search may show before it has to say it stopped.

Inherited from Assistant.Shell.IShellOutput.MatchLimit.

PropertyListingLimit

How many entries a listing may show before it has to say it stopped.

Inherited from Assistant.Shell.IShellOutput.ListingLimit.

PropertyTruncated

Whether the answer is missing something, because a limit stopped it.

Inherited from Assistant.Shell.IShellOutput.Truncated.

PropertyText

The answer, without a trailing line break.

Inherited from Assistant.Shell.IShellOutput.Text.

MethodLine(string)

Writes one line.

Inherited from Assistant.Shell.IShellOutput.Line.

Parameters

text
The line, without its line break.

MethodRaw(string)

Writes text as it stands, ending it with a line break unless it has one.

Inherited from Assistant.Shell.IShellOutput.Raw.

Parameters

text
The text.

MethodNote(string)

Writes a bracketed note that says something about the answer without cutting it short.

Inherited from Assistant.Shell.IShellOutput.Note.

Parameters

note
The note, without its brackets.

MethodStopped(string)

Writes the note that says a limit was reached, and marks the answer truncated.

Inherited from Assistant.Shell.IShellOutput.Stopped.

Parameters

note
The note, without its brackets.

Assistant.Shell.ShellReading

Reads the pages a command's operands named, or the refusal that says one is a folder.
Every command that reads pages refuses a folder the same way, naming the command in the result's summary, so the wording lives here rather than in each applet.

MethodPagesAsync(IReadOnlyList<Assistant.PageNode> paths, Assistant.IPageStoreReader store, string command, CancellationToken cancellationToken)

The files the paths name, in the order they were written, or the first refusal.

Parameters

paths
The operands, already expanded and validated.
store
The store to read them from.
command
The command's word, for the refusal's summary.
cancellationToken
The run's token.

Assistant.Shell.ShellRegistry

The shell's applets, by the word that runs them.
The table BusyBox keeps: one row per command, and everything about a command is on its row's applet. help reads this rather than a list of its own, so the help text cannot fall behind the commands.

MethodShellRegistry(IEnumerable<Assistant.Shell.ShellApplet> applets)

Builds the table from the applets, in ordinal order.

Parameters

applets
Every applet the shell answers.

PropertyAll

Every applet, in ordinal order.

MethodFind(string name)

The applet a word names, or null when the shell does not answer it.

Parameters

name
The command word.

Assistant.Shell.ShellResult

How a command, or a stage of the shell, ended.

MethodShellResult(bool IsSuccess, string Summary, string Error)

How a command, or a stage of the shell, ended.

Parameters

IsSuccess
Whether it did what it was asked.
Summary
One line for the tool result's summary.
Error
The refusal, when it failed.

PropertyIsSuccess

Whether it did what it was asked.

PropertySummary

One line for the tool result's summary.

PropertyError

The refusal, when it failed.

MethodOk(string summary)

What a command that worked answers with.

Parameters

summary
One line for the tool result's summary.

MethodRefused(string error, string summary)

What a command that refused answers with, and the reason it gives.

Parameters

error
The refusal.
summary
One line for the tool result's summary.

Assistant.Shell.ShellRunner

The kernel: it lexes a line, finds the applet, parses, expands, runs it and wraps the answer.
The whole of the shell's own behaviour is here, so an applet never parses its own command line and never builds the tool result. It also owns the one rule a line has to obey that a POSIX shell would not impose: no operators, yet. That rule lives here rather than in the lexer because it is temporary — a pipeline is a kernel stage, and the lexer already hands it the tokens.

PropertyRegistry

The table of applets, which help reads.

MethodRunAsync(string text, Editor.PageEditor pages, Assistant.PagePathPolicy paths, Assistant.AssistantOptions options, ContextBudget budget, CancellationToken cancellationToken)

Runs a line. Every command the shell answers is an applet, so this always answers.

Parameters

text
The command text.
pages
The editor behind the store.
paths
The path policy.
options
The assistant's options, for the applets' own limits.
budget
The content budget the answer is measured against.
cancellationToken
The run's token.

MethodOperatorRefusal(char character)

Why an unquoted operator is refused for now.
It says "yet" on purpose: pipelines and redirections are the next thing this grows.

Parameters

character
The operator the line carried.

Assistant.Shell.ShellText

Lines and numbers, the way a shell counts them.

MethodSplit(string text)

The lines of a text, where a line is what a line break terminates.
A final line break ends the last line rather than starting an empty one, so "one\n" is one line and "" is none — which is what POSIX counts, and what wc -l means.

Parameters

text
The text to split.

MethodNumber(string text)

A text with each line's number and a tab in front of it.

Parameters

text
The text to number.

Assistant.Shell.Applets

Assistant.Shell.Applets.CatApplet

Prints each page's source, one after another.

Assistant.Shell.Applets.DiffApplet

Compares two keys and writes what POSIX diff writes.

Assistant.Shell.Applets.FindApplet

Prints the keys at or below each path that match every test it was given.

Assistant.Shell.Applets.FindExpression

What a find line asks for: the tests, joined by and.
POSIX gives find an expression rather than options, so this is the command's own language, the way Assistant.GrepPattern is grep's. It is a subset: the primaries below, joined by an implicit and, and nothing else — an unknown one is refused by name rather than ignored.

Assistant.Shell.Applets.GrepApplet

Prints the lines that match a pattern, the keys that have one, or a count for each key.

Assistant.Shell.Applets.HeadApplet

Prints the first lines of each key.

Assistant.Shell.Applets.HeadOrTailApplet

Prints a counted number of lines from one end of each key.
The two commands are one option, one arity and one loop; only which end of the file they take differs, so that is the part each one writes.

MethodTake(string[] lines, int count)

The lines this command shows from a page's own lines.

Parameters

lines
Every line of the page.
count
How many to take.

Assistant.Shell.Applets.HelpApplet

The commands, and one command's syntax, read from the applets themselves.

Assistant.Shell.Applets.LsApplet

Lists what is at a path: the keys in it, or the path itself when it is a page.

Assistant.Shell.Applets.StatApplet

Prints a record for each key: its permission, size, revision and compile state.

Assistant.Shell.Applets.TailApplet

Prints the last lines of each key.

Assistant.Shell.Applets.WcApplet

Counts the lines of each key, as a shell's wc counts them.

Assistant.Tools

Assistant.Tools.AssistantTool

One tool: what it is called, what the model is told about it, and the code that runs it.

PropertySpec

Everything the model is told and the rest of the wiring asks about this tool.

MethodRunAsync(Assistant.Tools.ToolValues values, Assistant.Tools.ToolServices services, CancellationToken cancellationToken)

Runs the tool over arguments that have already been validated.

Parameters

values
The validated arguments.
services
The caller and the services this call may use.
cancellationToken
The run's token.

Assistant.Tools.CheckScriptTextTool

Checks the JavaScript in a complete page template supplied as content.

Assistant.Tools.CheckScriptTool

Checks the JavaScript a stored page serves.

Assistant.Tools.DeletePageTool

Tombstones a page, retaining its revisions.

Assistant.Tools.DiffPageTool

Compares two retained revisions of a page and returns a unified diff.

Assistant.Tools.EditPageTool

Replaces physical template lines if the revision is still the one read.

Assistant.Tools.FetchTool

Gets a URL over HTTP or HTTPS and returns its status, type and text body.

Assistant.Tools.ForgetMemoryTool

Deletes a memory and its history.

Assistant.Tools.ListPagesTool

Lists the live pages and shell files under an optional prefix.

Assistant.Tools.ListRevisionsTool

Lists a page's retained revisions, newest first.

Assistant.Tools.MemoryTools

What the memory tools share: the metric and the shape of a memory.

Assistant.Tools.PageToolData

What the page tools share: the line rule, the listing rows and the diagnostic shape.

FieldHashRefusal

The refusal a hash that is not 64 lowercase hexadecimal characters gets.

MethodLimitRefusal(Assistant.AssistantOptions options)

The refusal a limit outside the configured range gets.

Parameters

options
The assistant's configured listing limits.

MethodTryReadLimit(Assistant.Tools.ToolValues values, Assistant.AssistantOptions options, ref int limit)

Reads a caller's limit, or the configured default when it named none.

Parameters

values
The validated arguments.
options
The assistant's configured listing limits.
limit
The number of rows to answer with.

Returns

False when the argument was supplied and is outside the accepted range.

MethodProjectSource(string content, int? requestedStart, int? requestedEnd, ContextBudget budget)

Reads a source as a 1-based inclusive line range, windowed to the result budget.

`read_page` and `read_revision` read source through this one function, so a revision a tool quotes is numbered and windowed exactly as the live page is (`assistant-line-numbers-are-physical`).

Every line carries its number because the result is read as escaped JSON: counting lines in that is guesswork, and a number that is not on the line cannot be miscounted.

Parameters

content
The stored source.
requestedStart
The first line wanted, or null for the first.
requestedEnd
The last line wanted, or null for one line or the rest.
budget
The content budget the read is windowed to.

Returns

The range, or null when it is outside the source.

Assistant.Tools.PageToolData.ProjectedSource

One source read as a line range, windowed to fit the result budget.

MethodProjectedSource(string Text, int StartLine, int EndLine, int TotalLines, bool Truncated)

One source read as a line range, windowed to fit the result budget.

Parameters

Text
The lines the caller asked for, each prefixed with its 1-based number and | , or a head-and-tail window when they were too long.
StartLine
The first 1-based line in the answer.
EndLine
The last 1-based line in the answer.
TotalLines
How many lines the whole source has.
Truncated
Whether the text was windowed because it exceeded the budget.

PropertyText

The lines the caller asked for, each prefixed with its 1-based number and | , or a head-and-tail window when they were too long.

PropertyStartLine

The first 1-based line in the answer.

PropertyEndLine

The last 1-based line in the answer.

PropertyTotalLines

How many lines the whole source has.

PropertyTruncated

Whether the text was windowed because it exceeded the budget.

Assistant.Tools.ReadPageTool

Reads a page or a shell file's record, by line range.

Assistant.Tools.ReadRevisionTool

Reads one retained revision's stored source, by line range.

Assistant.Tools.ReferenceTool

Reads the page contract's own documentation: one type, or a search of the corpus.
The contract only. The page API admits uk.osric.asp.Sdk and a slice of the BCL, so documenting the host's own assemblies to the model would invite code the compiler refuses. The human page still covers all four.

Assistant.Tools.RememberTool

Stores something durable the owner has said about themselves or the site.

Assistant.Tools.RestoreRevisionTool

Restores one retained revision as a new revision of the page.

Assistant.Tools.SearchMemoriesTool

Searches the owner's memories by keyword.

Assistant.Tools.SearchPagesTool

Searches live page source and the shell files' records for a literal substring.

Assistant.Tools.ShellTool

Runs a read-only virtual-shell command over stored pages and the shell's files.

Assistant.Tools.ToolPaths

The gate every path-naming tool repeats, in the one order it must happen.
A write is validated against the policy and nothing more: the policy already refuses a reserved or protected key for a write. A read is validated the same way and then asked whether a reserved route shadows the key, because the policy permits a read beneath a reserved route and the tool must not. The refusal's summary uses the tool's own verb, so its wording has one source.

MethodResolveRead(Assistant.Tools.ToolSpec spec, Assistant.Tools.ToolValues values, string argument, Assistant.Tools.ToolServices services)

The path a read names, or the refusal that stops the call.

Parameters

spec
The tool, for its verb.
values
The validated arguments.
argument
The argument that carries the path.
services
The policy and where the refusal is written.

MethodResolveWrite(Assistant.Tools.ToolSpec spec, Assistant.Tools.ToolValues values, string argument, Assistant.Tools.ToolServices services)

The path a write names, or the refusal that stops the call.

Parameters

spec
The tool, for its verb.
values
The validated arguments.
argument
The argument that carries the path.
services
The policy and where the refusal is written.

MethodRequirePageSource(Assistant.Tools.ToolSpec spec, PagePath path, string reads, Assistant.Tools.ToolServices services)

The refusal a tool that needs page source gives a shell file, or null.

Parameters

spec
The tool, for its name and verb.
path
The path the tool was asked to read.
reads
What the tool reads, as a clause: "reads page source".
services
The policy and where the refusal is written.

MethodDescribe(PagePath path)

A path as a refusal may repeat it.

Parameters

path
The path to describe.

Assistant.Tools.ToolRegistry

The assistant's tools, in declaration order, by the name that calls them.
The table BusyBox keeps: one row per tool, and everything about a tool is on its type. The model's Definitions, the dispatcher, the approval gate and the transcript's "did this change a page" question all read this one list, so a tool is unreachable only by being unregistered. The order is not sorted: it is part of the request body and so of the provider's cached prefix.

MethodToolRegistry(Assistant.Tools.AssistantTool[] tools)

Builds the table from the tools, keeping the order they were declared in.

Parameters

tools
Every tool the assistant answers.

PropertyDefault

The assistant's own tools.

PropertyAll

Every tool, in declaration order.

PropertyDefinitions

What the model is offered, derived from the same list in the same order.

MethodFind(string name)

The tool a name calls, or null when the assistant does not answer it.

Parameters

name
The tool name.

Assistant.Tools.ToolResults

Writes the tool result envelope, so no tool can bypass the one budget.

MethodToolResults(ContextBudget budget)

Writes the tool result envelope, so no tool can bypass the one budget.

Parameters

budget
The content budget one tool result may spend.

MethodSuccess(object data, string summary)

A result carrying data.

Parameters

data
What the tool produced.
summary
One line for the transcript.

MethodFailure(string error, string summary)

A refusal, or a call that could not be completed.

Parameters

error
The refusal.
summary
One line for the transcript.

MethodRefusal(string error, string summary)

A refusal written without a budget, for a call that cannot run at all.
A refusal is a sentence this host wrote, so there is nothing here for a cap to cut.

Parameters

error
The refusal.
summary
One line for the transcript.

Returns

The envelope a refusal carries.

MethodBounded(object envelope, string summary, bool success)

A result, truncated at its cap so the head is kept and the cut is named.
A refusal would lose the information and the fact that there was information, so an oversized result is cut instead: the head travels, the envelope says truncated, and a note says where the cut was. Refusals stay for what they are for — an invalid argument, a stale revision, a path outside the writable prefix, a missing page.

Parameters

envelope
The envelope to serialize.
summary
One line for the transcript.
success
Whether the call did what it was asked.

Assistant.Tools.ToolServices

What one tool call may use: who asked, the policy, the options, and the services it reaches.
Built once per call from the executor's singletons and the one scope it opens. The page editor and the memory store are resolved only when a tool asks for them, so a tool that needs neither does not instantiate one.

MethodToolServices(IServiceProvider scope, Assistant.ToolContext context, Assistant.PagePathPolicy paths, Assistant.AssistantOptions options, ContextBudget budget, Assistant.AssistantMetrics metrics, Assistant.IAssistantFetcher fetcher)

What one tool call may use: who asked, the policy, the options, and the services it reaches.
Built once per call from the executor's singletons and the one scope it opens. The page editor and the memory store are resolved only when a tool asks for them, so a tool that needs neither does not instantiate one.

Parameters

scope
The per-call scope the scoped services come from.
context
The owner, conversation and run the call belongs to.
paths
The path policy.
options
The assistant's configured limits.
budget
The content budget a tool's answer is measured against.
metrics
Where the run's counters go.
fetcher
The HTTP fetch behind fetch.

PropertyContext

The owner, conversation and run the call belongs to.

PropertyPaths

The path policy.

PropertyOptions

The assistant's configured limits.

PropertyBudget

The model's window and the reply's floor, which every content cap is a fraction of.

PropertyMetrics

Where the run's counters go.

PropertyFetcher

The HTTP fetch behind fetch.

PropertyPages

The page editor, resolved from the call's scope: the writes, and nothing else.

PropertyStore

The one read seam over the page store, made once for the call.

PropertyEditorPath

The editor's own key, so a tool's link lands on the page the owner moved it to.

PropertyMemories

The owner's memories, resolved from the call's scope.

PropertyViews

The live view tokens, asked by run id so no tool ever holds the secret.

PropertySite

Where this host reaches the site it serves, which is what view resolves against.

PropertyResults

Shapes and bounds what a tool answers with.

PropertyReference

The documentation this build carries, read only when a tool asks for it.

Assistant.Tools.ToolSpec

One tool as it is offered to the model and validated when it is called.

MethodToolSpec(string Name, string Description, bool NeedsApproval, IReadOnlyList<ToolArgumentSchema> Arguments)

One tool as it is offered to the model and validated when it is called.

Parameters

Name
The tool's stable name.
Description
The provider-visible description.
NeedsApproval
Whether RequireApproval mode pauses before this tool runs.
Arguments
The complete set of accepted arguments.

PropertyName

The tool's stable name.

PropertyDescription

The provider-visible description.

PropertyNeedsApproval

Whether RequireApproval mode pauses before this tool runs.

PropertyArguments

The complete set of accepted arguments.

PropertyVerb

The one word the tool's refusals use, as in "Edit refused".

PropertyWrites

Whether a successful call changes a stored page.

PropertyPathArgument

The argument the path policy refuses before the owner is asked, or null.

Assistant.Tools.ToolValues

The arguments of one call, after Assistant.ToolArguments has validated them.
A tool reads a value by name and gets the CLR type its schema promised, so no tool touches a JsonElement. The Required accessors answer a value the schema made mandatory; the parse has already refused a call without it, so reaching one without it is a defect in the table rather than something the model can do.

MethodToolValues(IReadOnlyDictionary<string, JsonElement> values)

The arguments of one call, after Assistant.ToolArguments has validated them.
A tool reads a value by name and gets the CLR type its schema promised, so no tool touches a JsonElement. The Required accessors answer a value the schema made mandatory; the parse has already refused a call without it, so reaching one without it is a defect in the table rather than something the model can do.

Parameters

values
The validated arguments.

MethodString(string name)

A string argument, or null when it was not supplied.

Parameters

name
The argument's name.

MethodInteger(string name)

An integer argument, or null when it was not supplied.

Parameters

name
The argument's name.

MethodBoolean(string name)

A boolean argument, which is false when it was not supplied.

Parameters

name
The argument's name.

MethodHas(string name)

Whether an argument was supplied at all, even when its value is an empty array.

Parameters

name
The argument's name.

MethodArray(string name)

The objects in an array argument, each as its own validated argument set.

Parameters

name
The argument's name.

MethodRequiredString(string name)

A required string argument.

Parameters

name
The argument's name.

MethodRequiredInteger(string name)

A required integer argument.

Parameters

name
The argument's name.

Assistant.Tools.UpdateMemoryTool

Replaces a memory's content when it is out of date.

Assistant.Tools.ViewTool

GETs a path on this site as the run's owner, and returns the response as the server sent it.

The counterpart to fetch, which is anonymous and reaches any host. A path is this site as you; an absolute URL is fetch's job. There is nothing to approve: it reaches nothing but this site, writes nothing, and answers a question about the run's own work — the standing read_page has.

The value is the transport's own answer — every header, the body's own bytes read as UTF-8, the redirects it took — rather than `fetch`'s text projection. A body that is not UTF-8 comes back as base64 rather than as replacement characters, so a run never mistakes mangled text for the page.

Assistant.Tools.WritePageTool

Creates or deliberately replaces a complete page.

Authentication

Authentication.AuthTicket

An authentication ticket held on the server, keyed by the random value in the cookie.

PropertyKey

The random, unguessable key the cookie carries; 128 bits, base64url-encoded.

PropertyUserName

The account the ticket belongs to, so a sign-in never inherits another one's key.

PropertyProtectedTicket

The framework's own data-protected ticket, exactly as it would have gone in the cookie.

PropertyExpiresAt

When the ticket stops being valid, so a sweep can drop rows nobody returns to.
UTC, because SQLite can only compare and order the DateTime mapping.

Authentication.AuthTicketCleanupService

Drops stored authentication tickets that expired without a request to remove them.

MethodAuthTicketCleanupService(Authentication.AuthTicketStore, TimeProvider, ILogger<Authentication.AuthTicketCleanupService>)

Drops stored authentication tickets that expired without a request to remove them.

Authentication.AuthTicketStore

Reads and writes Authentication.AuthTicket rows, opening a scope per call.
Synchronous because ISecureDataFormat<T> is, and the work is one indexed statement against a local SQLite file.

MethodAuthTicketStore(IServiceScopeFactory)

Reads and writes Authentication.AuthTicket rows, opening a scope per call.
Synchronous because ISecureDataFormat<T> is, and the work is one indexed statement against a local SQLite file.

MethodFind(string key)

Finds the ticket stored under a key.

Parameters

key
The cookie's key.

Returns

The row, or null when the key is unknown.

MethodAdd(Authentication.AuthTicket ticket)

Adds a ticket under a key that is not yet stored.

Parameters

ticket
The row to add.

MethodUpdate(string key, string userName, string protectedTicket, DateTime expiresAt)

Replaces the ticket stored under a key, when the key still belongs to the account.

Parameters

key
The cookie's key.
userName
The account the new ticket belongs to.
protectedTicket
The framework's newly protected ticket.
expiresAt
The ticket's new expiry, in UTC.

Returns

Whether a row was updated.

MethodRemove(string key)

Deletes the ticket stored under a key.

Parameters

key
The cookie's key.

Returns

Whether a row was deleted.

MethodRemoveExpired(DateTime now)

Deletes rows whose ticket has expired, which no request will ever remove again.

Parameters

now
The current UTC time.

Returns

The number of rows deleted.

Authentication.AuthenticationExtensions

Registers the editor's local-account authentication and its protections.

FieldViewSchemeSelector

The name of the scheme that forwards by header, which is the default one.

MethodAddEditorAuthentication(IServiceCollection services, IWebHostEnvironment environment, Authentication.AuthenticationOptions authentication)

Adds cookie authentication, authorisation, antiforgery and login throttling.

Parameters

services
The service collection.
environment
The host environment, which decides the cookie secure policy.
authentication
The sign-in policy, read from configuration.

Authentication.AuthenticationFailures

Writes the one line a refused authentication leaves in the journal.

The wording is a contract with the host's ban: deploy/fail2ban/filter.d/uk.osric.asp.conf matches Authentication failed: and the client's address straight after it, and an address whose line appears too often is banned. Everything after the address is for the person reading the journal, so it can say what was refused without making the line hard to match.

A request that ends unauthenticated and was refused is the failure, whoever refused it: the view guard's 401, a challenge that sends the browser to sign in, a page's own ctx.Response.RedirectToLogin(). That is decided after the response is built, so the middleware agrees with every producer instead of repeating the rule at each one.

MethodApplyAsync(HttpContext context, RequestDelegate next)

Logs a request that ended unauthenticated and was refused.

Parameters

context
The request, before its response is written.
next
The rest of the pipeline, which decides the response.

MethodLog(HttpContext context, string reason)

Logs a refusal the request answers itself, such as a sign-in that renders its form again.

Parameters

context
The request being refused.
reason
What was refused, in a few words for the journal.

MethodLog(HttpContext context, string reason, string account)

Logs a refusal that has an account to name, which is a sign-in attempt.

Parameters

context
The request being refused.
reason
What was refused, in a few words for the journal.
account
What the request said it was signing in as.

Authentication.AuthenticationOptions

The sign-in policy: how long a cookie lasts and how hard a client may try.
Every value comes from Authentication.

PropertyTicketLifetime

How long a sign-in lasts without a visit before it is renewed or refused.

PropertyLogin

The login throttle.

MethodFromConfiguration(IConfiguration configuration)

Reads Authentication.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Authentication into the caller's report.

Parameters

reader
A reader opened on Authentication, which the caller completes.

Authentication.EditorPolicy

Names shared by the editor's authorisation policy and its cookies.

FieldName

The policy that protects the editor endpoints.

FieldSecurityStampClaim

The claim that carries the account's revocation stamp.

Authentication.LocalRedirect

Keeps a login redirect on this site.

MethodSafe(string returnUrl)

Returns the requested local path, or the site root when it is not safe.

Parameters

returnUrl
The value the browser supplied.

MethodIsSafe(string returnUrl)

Whether a value is a path on this site rather than an absolute or protocol-relative URL.

Parameters

returnUrl
The value to test.

Authentication.LoginEndpoint

Renders the sign-in form, accepts its POST and signs the visitor out.

MethodGetAsync(HttpContext, IAntiforgery)

Renders the sign-in form, or sends an authenticated visitor back to where they asked to go.

MethodPostAsync(HttpContext, Users.IUserStore, Users.IPasswordService, IAntiforgery, IAuthenticationService, Pages.IPageSessionStore, Authentication.PageSessionCookieOptions, ILoggerFactory)

Checks the local account and starts a cookie session.

MethodLogoutConfirmationAsync(HttpContext context, IAntiforgery antiforgery)

Asks the visitor to confirm signing out.
The menu links here rather than posting, because a GET a prefetcher follows must not end a session, and a post form in every document would carry an antiforgery field into pages a shared cache may store.

Parameters

context
The request being answered.
antiforgery
Mints the pair the confirmation form carries.

MethodLogoutAsync(HttpContext, IAuthenticationService, Pages.IPageSessionStore, Authentication.PageSessionCookieOptions, ILoggerFactory)

Deletes the authentication cookie and the visitor's page session.

MethodWriteExpiredFormAsync(HttpContext context, IAntiforgery antiforgery)

Re-renders the sign-in form after its token was rejected, with a fresh token.
A stale token can be answered before the endpoint runs, so the host's status-code fallback calls this too: a form that expired is a problem we can fix for the reader, not one to report at them.

Parameters

context
The rejected sign-in POST.
antiforgery
Mints the replacement token.

Authentication.LoginRateLimitOptions

The fixed window a client address may spend sign-in attempts in.
Read from Authentication:Login.

PropertyPermitLimit

Attempts allowed per window.

PropertyWindow

The length of the window.

Authentication.LoginRateLimitPolicy

Names the rate-limiting policy applied to the sign-in POST.

FieldName

The policy name used by routing and the limiter registration.

FieldBuckets

How many independent counters client addresses are folded into.
A power of two, so LoginRateLimitPolicy.BucketMask can mask where a modulo would divide. 1024 buckets bound the limiter's dictionary.

MethodPartitionFor(IPAddress address)

Names the bucket a client's attempts are counted in.
The limiter keeps a counter per key and never releases one, so the key cannot be an address the client chooses: folding addresses into a fixed set keeps that dictionary at a known size. Two clients share a bucket now and then, which is the price of the bound.

Parameters

address
The client's address, or null when the server could not supply one.

Returns

The bucket name, stable for an address.

Authentication.LoginRedirect

Builds the sign-in URL a page redirects an anonymous visitor to.
The target is built from the page's canonical key and the request's raw query, never from the page's collapsed query dictionary: a URL like /search?q=a&q=b must return to both values. Authentication.LocalRedirect is still the only thing that turns a returnUrl back into a location, so this helper cannot become an open redirect.

MethodLoginUrl(PagePath path, QueryString query)

The /login URL that returns to path with its query.

Parameters

path
The page's canonical key.
query
The request's query string, as it arrived.

Authentication.PageSessionCookie

Reads, mints, writes and clears the cookie that names one visitor's session.
A page cannot read or set this cookie: Set-Cookie is refused by SimpleContext's allow-list and HttpOnly keeps it from script. The value is 128 random bits in base64url, so a visitor cannot guess another's session, and this store never accepts a value it did not mint.

MethodMint()

Mints an unguessable session id.

Returns

128 random bits as base64url.

MethodRead(HttpContext context, Authentication.PageSessionCookieOptions options)

Reads the session id the visitor presented.

Parameters

context
The request being answered.
options
The cookie's name.

Returns

The id, or null when the cookie is absent or malformed.

MethodWrite(HttpContext context, string sessionId, Authentication.PageSessionCookieOptions options)

Writes the session cookie on a response that is not yet committed.

Parameters

context
The response being written.
sessionId
The id to carry.
options
The cookie's name and secure policy.

MethodClear(HttpContext context, Authentication.PageSessionCookieOptions options)

Deletes the cookie from the visitor's browser.

Parameters

context
The response being written.
options
The cookie's name and secure policy.

MethodRotateAsync(HttpContext context, Pages.IPageSessionStore store, Authentication.PageSessionCookieOptions options, string account, CancellationToken cancellationToken)

Discards the visitor's session and mints one that belongs to an account.
A sign-in rotates rather than adopts: the pre-existing row is deleted so the account cannot inherit what an anonymous visitor (or a previous account) left behind. A site with no room for another session leaves the visitor signed in without per-visitor state.

Parameters

context
The request being answered.
store
Where the session row lives.
options
The cookie's name and secure policy.
account
The normalised account name that now owns the session.
cancellationToken
Cancels the work.

Returns

Whether the new session was minted and its cookie written.

MethodClearAsync(HttpContext context, Pages.IPageSessionStore store, Authentication.PageSessionCookieOptions options, CancellationToken cancellationToken)

Deletes the visitor's session, if the request presented one.

Parameters

context
The request being answered.
store
Where the session row lives.
options
The cookie's name and secure policy.
cancellationToken
Cancels the work.

Authentication.PageSessionCookieOptions

How the page-session cookie is named and protected.

MethodPageSessionCookieOptions(string Name, CookieSecurePolicy SecurePolicy)

How the page-session cookie is named and protected.

Parameters

Name
The cookie's name.
SecurePolicy
Whether the cookie is only sent over HTTPS.

PropertyName

The cookie's name.

PropertySecurePolicy

Whether the cookie is only sent over HTTPS.

FieldDefaultName

The session cookie's name, one character beside the auth and antiforgery cookies.

MethodFor(IWebHostEnvironment environment)

Builds the options for an environment, using the same secure policy as the other cookies.

Parameters

environment
The host environment.

Authentication.SignedInOwner

The one place a request's owner id is read from its principal.
The id is the account name the sign-in ticket was minted for, and every owner-scoped store keys its rows by it. Reading it in one place is what keeps a second spelling of the claim — or a second idea of what "signed in" means — out of the shell.

MethodOf(HttpContext context)

The account the request is signed in as.

Parameters

context
The request being answered.

Returns

The owner id, or null when nothing is signed in.

Authentication.StoredTicketDataFormat

Puts a random key in the cookie and keeps the protected ticket in SQLite.
The handler never sees this difference: Protect still returns the cookie value and Unprotect still returns the ticket. The inner format is the framework's own, so serialisation and the data protection purposes stay exactly as they were.

MethodStoredTicketDataFormat(ISecureDataFormat<AuthenticationTicket> inner, Authentication.AuthTicketStore tickets, IHttpContextAccessor http, string cookieName)

Puts a random key in the cookie and keeps the protected ticket in SQLite.
The handler never sees this difference: Protect still returns the cookie value and Unprotect still returns the ticket. The inner format is the framework's own, so serialisation and the data protection purposes stay exactly as they were.

Parameters

inner
The framework format whose output is stored instead of sent.
tickets
The store that holds the protected ticket.
http
The current request, so a renewal can keep its key.
cookieName
The cookie the handler will set, and read to find the current key.

MethodMarkSignIn(HttpContext context)

Marks the request as an explicit sign-in, which always gets a new cookie key.
A sign-in must never keep a key the browser already had: a cookie planted for the origin would otherwise inherit the new session. Sliding renewal, which is not marked, keeps its key.

Parameters

context
The request that is about to sign in.

MethodProtect(AuthenticationTicket)

Inherited from ISecureDataFormat`1.Protect.

MethodProtect(AuthenticationTicket, string)

Inherited from ISecureDataFormat`1.Protect.

MethodUnprotect(string)

Inherited from ISecureDataFormat`1.Unprotect.

MethodUnprotect(string, string)

Inherited from ISecureDataFormat`1.Unprotect.

Authentication.ViewAuthenticationHandler

Authenticates the token a run presents to view the site it is serving.

The second scheme, and the only one that is not a sign-in: a request carrying Authorization: Bearer is authenticated here or nowhere, and it never falls back to the cookie. The account is validated the way the cookie's is validated on every request — it exists, and its security stamp has not moved — so users passwd in the middle of a run takes the view away.

A failed attempt is a failure, never an anonymous result: the caller asserted an identity, and Authentication.ViewGuard turns that into a 401 rather than a page a stranger would see.

MethodViewAuthenticationHandler(IOptionsMonitor<AuthenticationSchemeOptions>, ILoggerFactory, UrlEncoder, Authentication.ViewTokenStore)

Authenticates the token a run presents to view the site it is serving.

The second scheme, and the only one that is not a sign-in: a request carrying Authorization: Bearer is authenticated here or nowhere, and it never falls back to the cookie. The account is validated the way the cookie's is validated on every request — it exists, and its security stamp has not moved — so users passwd in the middle of a run takes the view away.

A failed attempt is a failure, never an anonymous result: the caller asserted an identity, and Authentication.ViewGuard turns that into a 401 rather than a page a stranger would see.

MethodHandleAuthenticateAsync()

Inherited from AuthenticationHandler`1.HandleAuthenticateAsync.

Authentication.ViewGuard

The two rules a view token is held to, in one place, before anything else sees the request.

A header that did not authenticate is a 401, never a silent anonymous view: the caller asserted an identity, and a page that quietly answers as a stranger is how "why is my page showing the sign-in form" becomes an afternoon.

A view reads and never writes. The check is here rather than on the page endpoint because the page endpoint covers pages only — the editor, the admin tools, the assistant and the memory page are all shell routes with their own POSTs — and a rule that has to be repeated by the next endpoint is a rule that will be forgotten by one. It runs before authorisation and long before the antiforgery check, so a token can never reach a form that changes state.

MethodApplyAsync(HttpContext context, RequestDelegate next)

Refuses a view that did not authenticate, and one that tries to write.

Parameters

context
The request.
next
The rest of the pipeline.

Authentication.ViewToken

One run's view of the site: the secret it presents and the owner it acts as.

It is not a password, not a session and not a sign-in. It exists because the process is already acting as this owner for this run, and it is dead when the run is; nothing stores it, so there is nothing to rotate and nothing to leak.

A class rather than a record, for the reason PageCredential is one: the generated ToString would print Secret, and a record's is printed by every scope that holds it.

FieldClaim

The claim that tells the guard a request carries a view.

FieldAuthenticationScheme

The authentication scheme's name, which is also the identity's authentication type.

FieldHeaderScheme

The scheme the secret is presented with in the Authorization header.

PropertySecret

The secret the fetcher presents as Authorization: Bearer.

PropertyRunId

The run this token belongs to, which is what the claim carries.

PropertyOwner

The account the run belongs to.

PropertySecurityStamp

The owner's revocation stamp when the run started, or null when the account was gone.

MethodCreate(string runId, string owner, string securityStamp)

Creates a token for one run.

Parameters

runId
The run's id.
owner
The account the run belongs to.
securityStamp
The account's stamp, read when the run started.

MethodToString()

Names the run and its owner, never the secret.

Returns

A line safe to log.

Authentication.ViewTokenStore

The view tokens of the runs that are executing right now.

One entry per live run, at most Assistant:MaxActiveRuns of them, and nowhere but this dictionary: no table, no file, no key-ring entry, no configuration key. A restart ends every run (assistant-a-run-is-not-resumed) and therefore every token, which is the lifetime the run already has rather than a second one to reason about.

Resolution scans the entries rather than indexing the secret. There are at most two, and a lookup by value could only answer faster, not more safely: the secret is 256 random bits, so finding one is already the only way in, and the comparison itself is fixed-time.

MethodViewTokenStore(Assistant.AssistantOptions)

The view tokens of the runs that are executing right now.

One entry per live run, at most Assistant:MaxActiveRuns of them, and nowhere but this dictionary: no table, no file, no key-ring entry, no configuration key. A restart ends every run (assistant-a-run-is-not-resumed) and therefore every token, which is the lifetime the run already has rather than a second one to reason about.

Resolution scans the entries rather than indexing the secret. There are at most two, and a lookup by value could only answer faster, not more safely: the secret is 256 random bits, so finding one is already the only way in, and the comparison itself is fixed-time.

MethodMint(string runId, string owner, string securityStamp)

Creates the token for a run that is about to execute.

Parameters

runId
The run's id.
owner
The account the run belongs to.
securityStamp
The owner's stamp when the run started, or null when the account is gone.

Returns

The token, which Forget must be given when the run ends.

Exceptions

InvalidOperationException
Every active run already holds one.

MethodForRun(string runId)

The token a run is presenting, or null when it holds none.

Parameters

runId
The run's id.

MethodTryResolve(string secret, ref Authentication.ViewToken token)

Resolves a presented secret, comparing it in fixed time.

Parameters

secret
The value the request presented.
token
The token it belongs to, when it belongs to one.

Returns

true when the secret is a live run's.

MethodForget(Authentication.ViewToken token)

Forgets a run's token, which is what makes it dead.

Parameters

token
The token Mint returned.

PropertyCount

How many runs hold a token, for a test and for the startup line.

Configuration

Configuration.ConfigurationException

Configuration the site cannot run without, reported once at startup.
It means "the operator has to change a setting", not "the site is broken", so the process writes the message to standard error and exits rather than logging a stack trace.

MethodConfigurationException(string)

Configuration the site cannot run without, reported once at startup.
It means "the operator has to change a setting", not "the site is broken", so the process writes the message to standard error and exits rather than logging a stack trace.

Configuration.ConfigurationReader

Reads one configuration section, collecting every problem before it reports.

Configuration is the only source of a policy value: there is no fallback in code, so a missing key stops the site at startup instead of quietly becoming a build-time default. A reader collects the whole section's problems — a missing key, a value of the wrong type, a value outside its range — and Complete throws one Configuration.ConfigurationException naming each, with the range and the value this repository ships. The recommendation is guidance for the operator, not a fallback: the value the site runs with is the one in appsettings.json.

A nested reader shares the problem list, so one Complete at the top of a factory reports a whole section's worth of mistakes in one start.

MethodConfigurationReader(IConfiguration configuration, string section)

Opens a section.

Parameters

configuration
The application configuration.
section
The section's path, such as Pages:Render.

PropertySection

The section this reader was opened on.

MethodFor(string key)

Opens a section below this one, sharing the problem list.

Parameters

key
The section's key.

MethodAt(string section)

Opens another section by its full path, sharing the problem list.
For a value one section borrows from another, such as a session key's length.

Parameters

section
The section's path from the configuration root.

MethodExists()

Whether this section exists at all.

MethodValueOrNull()

The section's own value, for a setting written as a string rather than a set of keys.

MethodHas(string key)

Whether a key below this section exists at all.

Parameters

key
The key, relative to this section.

MethodSectionOf(string key)

The configuration a key below this section holds, for a reader that has to walk it.

Parameters

key
The key, relative to this section.

MethodChildren(string key)

The entries of a section-like key below this one.

Parameters

key
The key, relative to this section.

MethodFail(string key, string problem)

Records a problem that the reader's own values could not express.

Parameters

key
The key it belongs to, relative to this section.
problem
The sentence, without a leading key and without a full stop.

MethodFail(string problem)

Records a problem that already names its key, such as a validator's complaint.

Parameters

problem
The whole sentence.

MethodFailIf(bool condition, string key, string problem)

Records a problem when a condition holds.

Parameters

condition
The condition that makes the configuration invalid.
key
The key it belongs to, relative to this section.
problem
The sentence, without a leading key and without a full stop.

MethodComplete()

Reports every problem collected so far, or returns.

Exceptions

One or more values are missing or unusable.

MethodText(string key, string example, bool allowEmpty)

A required string, such as a key or a host.

Parameters

key
The key, relative to this section.
example
What a good value looks like, for the message.
allowEmpty
Whether a blank value is a meaningful setting.

MethodOptionalText(string key)

A string that may be absent, for a value the site can genuinely do without.

Parameters

key
The key, relative to this section.

MethodValue(string example, bool allowEmpty)

A required section that is a value rather than a set of keys.

Parameters

example
What a good value looks like, for the message.
allowEmpty
Whether a blank value is a meaningful setting.

MethodNumber(string key, int recommended, int minimum, int maximum)

A required whole number, bounded so a mistake cannot switch the limit off.

Parameters

key
The key, relative to this section.
recommended
The value this repository ships, for the message.
minimum
The smallest value the site will run with.
maximum
The largest value the site will run with.

MethodNumber(string key, long recommended, long minimum, long maximum)

A required whole number too large for Int32.

Parameters

key
The key, relative to this section.
recommended
The value this repository ships, for the message.
minimum
The smallest value the site will run with.
maximum
The largest value the site will run with.

MethodDecimal(string key, double recommended, double minimum, double maximum)

A required fraction, such as a budget that may be part of a second.

Parameters

key
The key, relative to this section.
recommended
The value this repository ships, for the message.
minimum
The smallest value the site will run with.
maximum
The largest value the site will run with.

MethodSwitch(string key, bool recommended)

A required switch.

Parameters

key
The key, relative to this section.
recommended
The value this repository ships, for the message.

MethodMinutes(string key, int recommended, int minimum, int maximum)

A required count of minutes, bounded like a whole number.

Parameters

key
The key, relative to this section.
recommended
The value this repository ships, in minutes, for the message.
minimum
The smallest value, in minutes, the site will run with.
maximum
The largest value, in minutes, the site will run with.

MethodList(string key, string description, int minimum)

A required list of strings, such as the keys the site's own routes answer.

Parameters

key
The key, relative to this section.
description
What the entries are, for the message.
minimum
The fewest entries the site will run with.

Documentation

Documentation.ReferenceAssembly

One assembly's documentation as the page serves it.

MethodReferenceAssembly(Documentation.ReferenceAssemblyInfo Info, int TypeCount, int EntryCount, XDocument Document, Lazy<string> Html)

One assembly's documentation as the page serves it.

Parameters

Info
The assembly it describes.
TypeCount
How many type sections it holds.
EntryCount
How many documented entries the file carries.
Document
The normalised tree the tool reads.
Html
Its fragment, transformed on first use and kept for the process.

PropertyInfo

The assembly it describes.

PropertyTypeCount

How many type sections it holds.

PropertyEntryCount

How many documented entries the file carries.

PropertyDocument

The normalised tree the tool reads.

PropertyHtml

Its fragment, transformed on first use and kept for the process.

Documentation.ReferenceAssemblyInfo

One product assembly whose documentation this build carries.

MethodReferenceAssemblyInfo(string Slug, string AssemblyName, string Title, string Description)

One product assembly whose documentation this build carries.

Parameters

Slug
The URL segment that names it under /admin/reference.
AssemblyName
The assembly, which is also the XML file's name and its root namespace.
Title
The heading a reader sees.
Description
One line: what the assembly is for.

PropertySlug

The URL segment that names it under /admin/reference.

PropertyAssemblyName

The assembly, which is also the XML file's name and its root namespace.

PropertyTitle

The heading a reader sees.

PropertyDescription

One line: what the assembly is for.

PropertyAll

The four assemblies, in reading order: the contract first, then the host's layers.

Documentation.ReferenceDisplay

The string rules that turn a documentation id into a name, an anchor or a link.
Roslyn's member ids are the only identity the XML carries, and they are not a representation a reader wants: a parameter list names System.Collections.Generic.IReadOnlyList{System.String} and an explicit implementation has # where a dot belongs. Every rule here is a pure function over the id, so the corpus and the tool can be tested without a document.

FieldLearnBase

Where the API browser keeps a member.

MethodKind(string id)

The kind letter at the front of an id.

Parameters

id
A documentation id.

MethodBody(string id)

The id without its kind prefix.

Parameters

id
A documentation id.

MethodWithoutParameters(string id)

The id without its parameter list or conversion return type.

Parameters

id
A documentation id.

MethodParameters(string id)

The type names in the id's parameter list, in order.

Parameters

id
A documentation id.

MethodOwner(string id)

The type a member belongs to, or null for a type's own id.

Parameters

id
A documentation id.

MethodRelative(string id, string root)

The id without the assembly's root namespace.

Parameters

id
A documentation id.
root
The assembly name, which is its root namespace.

MethodTypeDisplay(string id, string root, IReadOnlyList<string> typeParameters)

A type as a reader sees it, with its documented type parameters.

Parameters

id
A type's id.
root
The assembly's root namespace.
typeParameters
The names from its typeparam elements, in order.

MethodMemberDisplay(string id, string root, IReadOnlyList<string> typeParameters, IReadOnlyList<string> methodTypeParameters, IReadOnlyList<string> parameterNames)

A member's signature: its name, type parameters and shortened parameter list.

Parameters

id
A member's id.
root
The assembly's root namespace.
typeParameters
The declaring type's type parameter names.
methodTypeParameters
The member's own type parameter names.
parameterNames
The names from its param elements, in order.

MethodMemberName(string id, string root, IReadOnlyList<string> methodTypeParameters)

A member's name alone, for a sentence that links to it.

Parameters

id
A member's id.
root
The assembly's root namespace.
methodTypeParameters
The member's own type parameter names.

MethodAnchor(string id, string root, IReadOnlyList<string> typeParameters, IReadOnlyList<string> methodTypeParameters)

The anchor a type or member is addressed by.

Parameters

id
A documentation id.
root
The assembly's root namespace.
typeParameters
The declaring type's type parameter names.
methodTypeParameters
The member's own type parameter names.

MethodLearnUrl(string id)

The API browser's page for a platform member, or null when it cannot be computed.

Parameters

id
An id the corpus does not hold.

MethodCrefText(string id)

An unresolved id as a short phrase, for a link's text or a code span.

Parameters

id
A documentation id.

MethodKindName(char kind)

The word a kind letter stands for.

Parameters

kind
The letter.

Documentation.ReferenceDocIds

Rebuilds the documentation id Roslyn writes from the reflected member.
The XML carries no token, file or line: an id is the only handle on a member, and inheritdoc resolution has to go from an id to a member and back to another id. The rules are Roslyn's, and the suite proves this bridge by rebuilding every id in the four real files.

MethodOf(MemberInfo member)

The id of a type or member.

Parameters

member
The reflected member.

MethodOf(Type type)

The id of a type.

Parameters

type
The reflected type.

MethodMap(Assembly assembly)

Every type and member of an assembly, by id.
A member whose id cannot be built is left out; the entry that names it keeps its note.

Parameters

assembly
The assembly to scan.

Documentation.ReferenceDocument

The normalised documentation of one assembly.

MethodReferenceDocument(Documentation.ReferenceAssemblyInfo Info, XDocument Content, int TypeCount, int EntryCount, IReadOnlyDictionary<string, Documentation.ReferenceEntry> Entries)

The normalised documentation of one assembly.

Parameters

Info
The assembly it describes.
Content
The XML the stylesheet transforms.
TypeCount
How many type sections it holds.
EntryCount
How many documented entries the source file carries.
Entries
Every type and member, by its raw id.

PropertyInfo

The assembly it describes.

PropertyContent

The XML the stylesheet transforms.

PropertyTypeCount

How many type sections it holds.

PropertyEntryCount

How many documented entries the source file carries.

PropertyEntries

Every type and member, by its raw id.

MethodBuild(Documentation.ReferenceAssemblyInfo info, XDocument source)

Parses one XML file into the document the corpus and the stylesheet use.

Parameters

info
The assembly the file belongs to.
source
The parsed file.

Exceptions

InvalidDataException
The file has no members element.

Documentation.ReferenceEndpoint

The two pages that read the documentation this build carries.
The shell owns these routes because the XML is a build artifact the image carries, like the changelist: a page cannot read a file beside the assembly. Both are public even though the key is under /admin — the URL is a filing cabinet, not an authorisation — and both render the admin menu because that is where a reader finds them.

MethodIndexAsync(HttpContext context, Documentation.ReferenceLibrary library, CancellationToken cancellationToken)

Answers GET /admin/reference: this build's assemblies.

Parameters

context
The response being written.
library
The corpus this build carries.
cancellationToken
Aborted when the request is abandoned.

MethodAssemblyAsync(HttpContext context, string slug, Documentation.ReferenceLibrary library, CancellationToken cancellationToken)

Answers GET /admin/reference/{slug}: one assembly.

Parameters

context
The response being written.
slug
The assembly's URL segment.
library
The corpus this build carries.
cancellationToken
Aborted when the request is abandoned.

Documentation.ReferenceEntry

One type or member as the corpus addresses it.

MethodReferenceEntry(string Id, string Anchor, string Kind, string Display, string Text, bool IsType)

One type or member as the corpus addresses it.

Parameters

Id
The raw documentation id.
Anchor
The URL fragment its section carries.
Kind
The word for its kind.
Display
Its signature, or a type's name with its type parameters.
Text
Its name alone, for a sentence that links to it.
IsType
Whether it is a type section rather than a member.

PropertyId

The raw documentation id.

PropertyAnchor

The URL fragment its section carries.

PropertyKind

The word for its kind.

PropertyDisplay

Its signature, or a type's name with its type parameters.

PropertyText

Its name alone, for a sentence that links to it.

PropertyIsType

Whether it is a type section rather than a member.

Documentation.ReferenceInheritance

Copies an inheritdoc entry's text down from the member it inherits.

The XML says <inheritdoc/> and nothing else, and the compiler does not write the source it meant. The assemblies are in this process, so the source can be named exactly: an override's base definition, the interface member the implementation maps to, or a type's base.

The copy is best-effort. A source outside the corpus (the BCL, EF Core) is named and, where the API browser has a page, linked; a member reflection cannot name keeps the note. Nothing here can fail a request.

MethodResolve(IReadOnlyList<Documentation.ReferenceDocument> documents, ILogger logger)

Resolves every inherit-only entry in place.

Parameters

documents
The corpus, already normalised and with its anchors.
logger
Where a summary line goes.

Documentation.ReferenceLibrary

The documentation this build carries, read once and held for the process.
The files cannot change while the image runs, so one read is enough. Loading is lazy: a host that never answers /admin/reference and never calls the tool pays nothing. Every failure is a missing assembly or a missing copy, never a request that fails.

FieldContractSlug

The slug the assistant tool reads.

MethodReferenceLibrary(string directory, ILogger<Documentation.ReferenceLibrary> logger)

Reads the files in a directory on first use.

Parameters

directory
Where the assemblies' XML files sit.
logger
Where a missing or malformed file is reported.

PropertyAssemblies

The assemblies this build carries, in reading order.

MethodFind(string slug)

One assembly by its URL segment, or null when this build does not carry it.

Parameters

slug
The segment under /admin/reference.

MethodRender(string slug)

One assembly's fragment, transformed on first use.

Parameters

slug
The segment under /admin/reference.

MethodFindType(string name)

A type by local name, relative name, generic form or raw id.

Parameters

name
What the model named.

MethodSearch(string query, int limit)

Searches the page contract's names and summaries.

Parameters

query
What to look for, case-insensitively.
limit
The most matches to return.

PropertyContract

The page contract's document, for the tool, or null when the build carries none.

Documentation.ReferenceRenderer

Transforms one normalised document into the fragment a shell page writes.
The stylesheet is embedded rather than seeded: it is the shell's presentation, not owner-editable content, and it cannot drift from the attributes the normaliser writes. It is loaded once with XsltSettings.Default and a null resolver, so script blocks and document() are off.

MethodRender(XDocument document)

The fragment for one assembly.

Parameters

document
The normalised document.

Documentation.ReferenceSearchMatch

One line of a reference search.

MethodReferenceSearchMatch(string Type, string Member, string Kind, string Summary)

One line of a reference search.

Parameters

Type
The type that holds the match.
Member
The member, or null when the type itself matched.
Kind
The word for the match's kind.
Summary
Its summary text, flattened.

PropertyType

The type that holds the match.

PropertyMember

The member, or null when the type itself matched.

PropertyKind

The word for the match's kind.

PropertySummary

Its summary text, flattened.

Documentation.ReferenceText

Flattens a documentation element to the text the assistant hears.
The page and the tool read one tree; this is the second output, not a second parser. Paragraphs become blank-separated text, lists become lines, and an inline element becomes its own words.

MethodFlatten(XElement element)

The text of a summary, remarks or other block, with whitespace tidied.

Parameters

element
The element to flatten.

Documentation.ReferenceTypeLookup

What a type lookup found: one type, several, one elsewhere, or nothing.

MethodReferenceTypeLookup(Documentation.ReferenceTypeMatch Match, IReadOnlyList<Documentation.ReferenceTypeMatch> Candidates, Documentation.ReferenceTypeMatch Elsewhere)

What a type lookup found: one type, several, one elsewhere, or nothing.

Parameters

Match
The one type in the page contract, when the name is unambiguous.
Candidates
The matches when the name is ambiguous.
Elsewhere
A type of that name in another carried assembly.

PropertyMatch

The one type in the page contract, when the name is unambiguous.

PropertyCandidates

The matches when the name is ambiguous.

PropertyElsewhere

A type of that name in another carried assembly.

Documentation.ReferenceTypeMatch

A type the tool found, with the document it belongs to.

MethodReferenceTypeMatch(Documentation.ReferenceAssemblyInfo Info, XElement Type)

A type the tool found, with the document it belongs to.

Parameters

Info
The assembly.
Type
Its type element.

PropertyInfo

The assembly.

PropertyType

Its type element.

Editor

Editor.ConditionalPageSaveResult

The outcome of a save that applies only while the head still has the expected revision.

MethodConditionalPageSaveResult(bool, string, IReadOnlyList<PageDiagnostic>)

The outcome of a save that applies only while the head still has the expected revision.

Editor.PageEditor

Reads and saves pages for the store's write capability.

A save compiles before it stores, so the page never sits in the database without the result of compiling it. That is Editor.PageSaver's job, and it is shared with a page that saves its own source; this class is the capability's view of it, for both the bound save and the conditional one every page may now make (`pages-a-page-may-save-itself`).

The unconditional save records page.save.duration through the saver; the conditional one shares the saver's accounting so a conflict and a plain save are counted alike.

MethodPageEditor(Pages.IPageStore, Editor.PageSaver)

Reads and saves pages for the store's write capability.

A save compiles before it stores, so the page never sits in the database without the result of compiling it. That is Editor.PageSaver's job, and it is shared with a page that saves its own source; this class is the capability's view of it, for both the bound save and the conditional one every page may now make (`pages-a-page-may-save-itself`).

The unconditional save records page.save.duration through the saver; the conditional one shares the saver's accounting so a conflict and a plain save are counted alike.

MethodGetAsync(PagePath path, CancellationToken cancellationToken)

Reads a page without compiling it.

Parameters

path
The canonical key to read.
cancellationToken
Cancels the read.

PropertyRuntimeId

The build that compiled the images this editor serves and saves.

MethodGetRevisionAsync(PagePath path, string hash, CancellationToken cancellationToken)

The revision with that hash, only when it is a revision of this page.
A hash is an address for one save, not for one page, so a link that carries another page's hash must read as no revision at all rather than as that page's source.

Parameters

path
The page the revision must belong to.
hash
The canonical hash a listing or a form carried.
cancellationToken
Cancels the read.

Returns

The revision, or null when no revision of this page has that hash.

MethodAdoptAsync(PagePath path, string seedHash, CancellationToken cancellationToken)

Records a seed as installed when the page already holds exactly its bytes.

Parameters

path
The canonical key.
seedHash
The hash of the seed the page's content equals.
cancellationToken
Cancels the write.

MethodSaveAsync(PagePath path, string template, CancellationToken cancellationToken, CancellationToken renderDeadline)

Builds a page's image and stores it with the template.

Parameters

path
The canonical key to save.
template
The template text.
cancellationToken
Cancels the write.
renderDeadline
The token of the render that asked for the save, or default when no page is waiting; a compile bounded by it can be given up on without losing the save.

Returns

The revision that became the page's head and the compiler's author-facing diagnostics, so a caller that reports the save can name the revision without a second read.

MethodSaveSeedAsync(PagePath path, string template, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)

Compiles and saves a seed's bundled source, recording it as the page's anchor.

Parameters

path
The canonical key to save.
template
The bundled source.
seedHash
The hash of the seed being installed.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline, when the save was made from inside a render.

MethodSaveIfRevisionAsync(PagePath, string, string, CancellationToken, CancellationToken)

Compiles and saves a page only while its current revision hash still matches.

MethodSaveSeedIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)

Compiles and saves a seed only while the head still has the expected revision.

Parameters

path
The canonical key to save.
template
The bundled source.
expectedRevisionHash
The hash the caller saw as the head.
seedHash
The hash of the seed being installed.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline, when the save was made from inside a render.

Editor.PageSaver

Compiles a template and stores it as a revision.

This is the one save: the editor, the seed restore, the assistant's save tools and a page saving its own source all end up here. A save compiles before it stores, so the page never sits in the database without the result of compiling it, and a compiler fault is the one case where the template is stored without an image — losing the author's edit to report our bug would be the worse failure (`pages-a-compiler-fault-is-ours`, `pages-a-warning-never-stops-a-page`).

It is a singleton because a page's save runs after the request that started it may have gone, and it writes through Pages.IPageRevisionStore for the same reason (`pages-the-store-is-read-through-one-seam`, `pages-a-page-may-save-itself`). A caller that owns a request's context still reads through Pages.IPageStore; only the write is shared.

Records page.save.duration.

MethodPageSaver(Pages.IPageRevisionStore, Pages.PageImageBuilder, Pages.PageLibraries, Pages.PageMetrics, ILogger<Editor.PageSaver>)

Compiles a template and stores it as a revision.

This is the one save: the editor, the seed restore, the assistant's save tools and a page saving its own source all end up here. A save compiles before it stores, so the page never sits in the database without the result of compiling it, and a compiler fault is the one case where the template is stored without an image — losing the author's edit to report our bug would be the worse failure (`pages-a-compiler-fault-is-ours`, `pages-a-warning-never-stops-a-page`).

It is a singleton because a page's save runs after the request that started it may have gone, and it writes through Pages.IPageRevisionStore for the same reason (`pages-the-store-is-read-through-one-seam`, `pages-a-page-may-save-itself`). A caller that owns a request's context still reads through Pages.IPageStore; only the write is shared.

Records page.save.duration.

PropertyRuntimeId

The build that compiled the images this saver stores.

MethodSaveAsync(PagePath path, string template, CancellationToken cancellationToken, CancellationToken renderDeadline)

Builds a page's image and stores it with the template.

Parameters

path
The canonical key to save.
template
The template text.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline when the save was made from inside a render. It bounds the wait for a compile slot and nothing else: the compile itself and the insert are left to finish, because losing the author's edit is the one loss this site refuses (`pages-a-page-may-save-itself`).

Returns

The revision the save stored and the compiler's author-facing diagnostics.

MethodSaveSeedAsync(PagePath path, string template, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)

Compiles and stores a seed's bundled source, recording it as the page's anchor.

Parameters

path
The canonical key to save.
template
The bundled source.
seedHash
The hash of the seed being installed.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline, when the save was made from inside a render.

Returns

The revision the save stored and the compiler's author-facing diagnostics.

MethodSaveIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, CancellationToken cancellationToken, CancellationToken renderDeadline)

Compiles and stores a page only while its current revision hash still matches.

Parameters

path
The canonical key to save.
template
The template text.
expectedRevisionHash
The hash the caller saw as the head.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline, when the save was made from inside a render.

Returns

The stored revision and diagnostics, or ConditionalPageSaveResult.Saved false when the head moved.

MethodSaveSeedIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)

A conditional seed write: stores the seed only while the head still has the expected hash.

Parameters

path
The canonical key to save.
template
The bundled source.
expectedRevisionHash
The hash the caller saw as the head.
seedHash
The hash of the seed being installed.
cancellationToken
Cancels the write.
renderDeadline
The render's deadline, when the save was made from inside a render.

Returns

The stored revision and diagnostics, or ConditionalPageSaveResult.Saved false when the head moved.

MethodRecordSaveFailed(PagePath path, long start)

Records a save that kept its source but produced no image.

Parameters

path
The page that was saved.
start
When the save started.

MethodRecordSaved(PagePath path, Pages.PageImage image, long start)

Records a save made through another path, so every save is counted alike.
The editor's conditional save compiles through the same builder but writes through its own request's store, so it shares this line rather than repeating it.

Parameters

path
The page that was saved.
image
What compiling it produced.
start
When the save started.

Editor.SavedRevision

What a save stored, and what compiling it reported.

MethodSavedRevision(Pages.PageTemplate Revision, IReadOnlyList<PageDiagnostic> Diagnostics)

What a save stored, and what compiling it reported.

Parameters

Revision
The revision that became the page's head.
Diagnostics
The compiler's author-facing answer; empty when the page compiled cleanly.

PropertyRevision

The revision that became the page's head.

PropertyDiagnostics

The compiler's author-facing answer; empty when the page compiled cleanly.

Errors

Errors.ErrorAudience

Decides whether a failed request wants a document or a problem document.

MethodPrefersJson(HttpRequest request)

Whether a request accepts JSON and does not also prefer HTML.
A browser sends text/html first and a wildcard last, so HTML wins whenever it is named. Anything that names only JSON, or a +json type, is talking to a program. A request that names neither is treated as a browser: a person is the more likely caller, and a human who gets a document can still read it, where a program given HTML cannot.

Parameters

request
The request to read.

Errors.ErrorEndpoint

Writes the error page from inside the exception handler.

MethodHandleAsync(HttpContext context)

Writes the error page. Runs inside the exception handler's branch, not from routing.

Parameters

context
The failing request.

Errors.ErrorMessage

One failure, worded for the person who hit it: what went wrong and what to do next.
One failure, worded for the person who hit it: what went wrong and what to do next.

Parameters

Code
A stable machine-readable name, sent to programs as the problem's extension member.
Title
A short summary, which becomes the page heading.
Summary
One or two sentences naming the problem in plain words.
Remedies
Where the reader can go to recover, in reading order. Empty for an error that is only ever written as a problem document.

PropertyCode

A stable machine-readable name, sent to programs as the problem's extension member.

PropertyTitle

A short summary, which becomes the page heading.

PropertySummary

One or two sentences naming the problem in plain words.

PropertyRemedies

Where the reader can go to recover, in reading order. Empty for an error that is only ever written as a problem document.

MethodForStatus(int statusCode, bool isAuthenticated, string editorPath)

The wording for a status no call site described, so no response is ever blank.

Parameters

statusCode
The response status to explain.
isAuthenticated
Whether the reader is signed in, which adds the editor's links.
editorPath
The editor's own key, which is configuration.

MethodFormExpired(bool isAuthenticated, string editorPath)

The wording for a form the host refused before an endpoint could read it.
A stale antiforgery token is the most common 400 a person sees, and the one case that has to promise the work was not lost with the form.

Parameters

isAuthenticated
Whether the reader is signed in.
editorPath
The editor key the remedies link to.

MethodDefaultRemedies(bool isAuthenticated, string editorPath)

The links every page offers: the editor when signed in, the way back always.

Parameters

isAuthenticated
Whether the reader is signed in.
editorPath
The editor's own key, which is configuration.

Errors.ErrorResponses

Writes a failed response for whichever audience asked for it.
Nobody is handed an empty body. A browser gets the document shell with a heading, an explanation and links that lead somewhere useful; a program gets an RFC 9457 problem document. Call sites that know something specific say it; ForStatus covers everything that does not, which is what the status-code fallback in the host uses.

The document also offers the editor for the page the request named, when the reader is signed in and the key is one the page route owns. That is derived from the request rather than passed in, so no call site can forget it, and a shell route's failure cannot offer to edit a page that does not exist.

MethodWriteAsync(HttpContext context, int statusCode, Errors.ErrorMessage message, CancellationToken cancellationToken)

Writes the error as HTML or as a problem document, whichever the request accepts.

Parameters

context
The failing request.
statusCode
The status to send.
message
What to say.
cancellationToken
Cancels the write; the request's own token when none is given.

MethodWriteHtmlAsync(HttpContext context, int statusCode, Errors.ErrorMessage message, string detailsHtml, CancellationToken cancellationToken)

Writes the error as a document: heading, explanation, recovery links, code and reference.

Parameters

context
The failing request.
statusCode
The status to send.
message
What to say.
detailsHtml
Extra markup written between the explanation and the recovery links, for a view that knows something the message cannot carry. It is the caller's markup, not a request value, so nothing here encodes it.
cancellationToken
Cancels the write.

MethodWriteJsonAsync(HttpContext context, int statusCode, Errors.ErrorMessage message, CancellationToken cancellationToken)

Writes the error as an RFC 9457 problem document, with the message code as an extension member.

Parameters

context
The failing request.
statusCode
The status to send.
message
What to say.
cancellationToken
Cancels the write.

MethodProblem(int statusCode, Errors.ErrorMessage message)

The error as an IResult, for an endpoint that has to return one.
The result writes through WriteJsonAsync, so an endpoint that answers with a result and one that writes the response directly cannot drift into two problem shapes.

Parameters

statusCode
The status to send.
message
What to say.

Health

Health.AbandonedRenderHealthCheck

Reports unhealthy once pages have wedged too many renders for too long.
A page that never returns cannot be interrupted, so the process that owns it has to die. This is how the site asks for that: the podman health check probes /health, and three failures restart the container. It deliberately does not guess at CPU or memory — those belong to the container's own limits.

MethodAbandonedRenderHealthCheck(Pages.PageHealth)

Reports unhealthy once pages have wedged too many renders for too long.
A page that never returns cannot be interrupted, so the process that owns it has to die. This is how the site asks for that: the podman health check probes /health, and three failures restart the container. It deliberately does not guess at CPU or memory — those belong to the container's own limits.

MethodCheckHealthAsync(HealthCheckContext, CancellationToken)

Inherited from IHealthCheck.CheckHealthAsync.

Health.ReportWriter

Renders a health report as the JSON body of the /health response.

MethodWriteAsync(HttpContext, HealthReport)

Writes the report, answering 200 when healthy and 503 otherwise.

Health.StorageHealthCheck

Reports whether SQLite is reachable: a host that cannot read storage is not up.

MethodStorageHealthCheck(IServiceScopeFactory)

Reports whether SQLite is reachable: a host that cannot read storage is not up.

MethodCheckHealthAsync(HealthCheckContext, CancellationToken)

Inherited from IHealthCheck.CheckHealthAsync.

Html

Html.AntiforgeryField

The one renderer of the antiforgery field every mutating form carries.

MethodHidden(AntiforgeryTokenSet tokens)

Renders the hidden input that carries the antiforgery pair in a form.
Every mutating form carries this field, and one renderer means a change to that contract cannot reach six views and miss the seventh.

Parameters

tokens
The tokens for this request.

Html.DiagnosticLine

One line of a diagnostics block.

MethodDiagnosticLine(string Text, PageDiagnosticSeverity? Severity, int? Line)

One line of a diagnostics block.

Parameters

Text
The message, unencoded: Diagnostics encodes it.
Severity
The severity, or null for a line that carries none, such as a stack location.
Line
The source line the line points at, when it points at one.

PropertyText

The message, unencoded: Diagnostics encodes it.

PropertySeverity

The severity, or null for a line that carries none, such as a stack location.

PropertyLine

The source line the line points at, when it points at one.

MethodFrom(IReadOnlyList<PageDiagnostic> diagnostics)

Turns compiler diagnostics into lines, ordered by source position.

Parameters

diagnostics
The diagnostics to show.

Returns

One line per diagnostic, in the order it should be read.

Html.Markup

The one HTML encoder the shell writes text through.
A page's own text is escaped by the template and a response's headers by the framework; this is for the shell's own markup, where a value from storage, a request or the provider is written between tags or into an attribute. It is a name for the rule rather than a second implementation: every call site writes Encode(value) and cannot reach for an unescaped string by accident.

MethodEncode(string value)

Escapes a value for HTML text or a double-quoted attribute.

Parameters

value
The value to escape.

Returns

The value with markup characters replaced by entities.

Html.PageLayout

Renders the editor's source-line gutter.

MethodGutter(int lineCount)

Renders one number per source line, each an anchor a diagnostic can point at.
Decorative, so the container is hidden from assistive technology: the textarea already holds the text, and the diagnostic link says its position in words. No whitespace between the spans, because one number per row is the whole layout.

Parameters

lineCount
The number of source lines, from Count.

MethodDiagnostics(IReadOnlyList<Html.DiagnosticLine> lines, bool linkToLines)

Renders diagnostic lines as a list, encoding every message.
role="list" is deliberate: the sheet removes the markers, and a list styled that way keeps its semantics only where the role says so.

Parameters

lines
The lines to show, in the order given.
linkToLines
Whether a line with a number links to that gutter number.

Html.ShellDocument

Writes the document every shell view is served in, and the pieces it is built from.

The shell owns this document because the error, sign-in, status and admin routes must answer when the page pipeline is broken, so it cannot depend on a stored page. The stored layout writes its own document, through the Site.Document library the site seeds; the two are kept honest by a test that compares their shape rather than by sharing a builder.

The fragments here still own the document's policy — the language, the charset, the sheet order, the icon, the skip link, the landmark and the close — so a view cannot forget one. They own no response policy: status, content type, security headers, caching and the body cap stay in BeginAsync.

Every builder returns markup rather than writing it, so the shell writes it to its own response. Encoding happens here: the title and every attribute are escaped, so a caller passes raw values.

FieldSkipLinkText

The text of the link that skips the chrome.

FieldShellClass

The class every shell document's body carries, so a reader can tell it from a page.

FieldShellLabelText

The visible label that says a shell document's menu is the site's tools.

PropertyBaseStylesheets

The sheets every document links before its own, in this order.
/site.css carries the document's shape and the site's look, so a page sheet overrides a structural rule without a more specific selector.

MethodIsSiteRelative(string href)

Whether a value is a path on this site rather than an absolute or protocol-relative URL.
A sheet or a redirect has to stay on this origin: the site's own policy answers with style-src 'self', so an off-site sheet would be blocked silently rather than fail.

Parameters

href
The value to test.

MethodHead(string title, IReadOnlyList<string> stylesheets, string head, string bodyClass, Func<string, string> resolveHref)

Renders the doctype, the head and the open body.

Parameters

title
The document title, encoded here; it may not be blank.
stylesheets
The view's own sheets, in the order it asked for them, linked after BaseStylesheets. An exact duplicate is linked once.
head
Raw markup written into head last, for a document that describes itself.
bodyClass
A class for body, added after the shell's own marker.
resolveHref
Resolves each sheet and the icon before it is written, or null to write the values as given. The caller owns the resolver, so this stays a pure string builder.

Exceptions

ArgumentException
The title is blank or a sheet is not site-relative.

MethodBanner(string navigation)

Writes the skip link and the banner around a navigation landmark.
The skip link is the first focusable thing in the body and points at the one main, so it is a property of the document rather than a habit of each caller. The label is text rather than a style, so a shell page still says what it is with no sheet and to a screen reader: its menu is the site's tools, not the pages the store holds.

Parameters

navigation
The nav markup, normally from Nav.
Renders a navigation landmark from its label and links.
The label is required, so an unnamed navigation landmark cannot be written.

Parameters

label
The landmark's accessible name, which no other nav may repeat.
links
The links, in reading order.
className
A class for the nav, when the view styles it.

Exceptions

ArgumentException
The label is blank.

MethodOpenMain()

Opens the one main landmark, which the skip link targets.

MethodCloseMain()

Closes the landmark OpenMain opened.

MethodFooter()

The footer every document carries, matching the seeded layout's.

MethodEnd()

Closes the document.

MethodBeginAsync(HttpContext context, string title, string navigation, int statusCode, IReadOnlyList<string> stylesheets, string bodyClass, string head, CancellationToken cancellationToken)

Starts a shell document: the head, the banner and the open main landmark.
One place owns the response, and the fragments above own the markup, so a view cannot forget the banner, the skip link or the landmark.

Parameters

context
The response being written.
title
The document title, encoded by the builder.
navigation
The site menu, normally For. It is required so a view cannot be written without one.
statusCode
The response status.
stylesheets
The sheets the view needs, after /site.css, in the order given.
bodyClass
A class for body, added after the shell's own marker.
head
Raw markup written into head after the stylesheets, for a document that describes itself — a progress page's refresh is the only user. It is the caller's markup, not a value from a request, so nothing needs encoding.
cancellationToken
Cancels the write.

MethodAssetUrlAsync(HttpContext context, string href, CancellationToken cancellationToken)

Versions a link one of the shell's own views writes in its head markup.

Parameters

context
The request whose asset map the link resolves against.
href
The site-relative link, such as a script's path.
cancellationToken
Cancels the read.

Returns

The versioned URL, or the link unchanged when it is not a live asset.

MethodEndAsync(HttpContext context, CancellationToken cancellationToken)

Closes the landmark and the document.

Parameters

context
The response being written.
cancellationToken
Cancels the write.

Html.SiteNavigation

The site menu the shell's own views carry.

The seeded /_layout writes the same menu for stored pages, from the same list of links, so the two copies are deliberate: the shell's document must not depend on a stored page, because the error, health, sign-in and editor routes have to answer when the page pipeline is broken.

The layout reads the links through ShellLinks; this filters the same values for the shell's own document and marks the same current item.

FieldLabel

The label no other navigation landmark may repeat.

FieldClass

The class the menu's nav carries, so the sheets can style it.

MethodFor(HttpContext context)

The menu for the request being answered.

Parameters

context
The request whose principal and path decide the items.

MethodNav(bool authenticated, string path, string query, string editorPath)

The rendered menu, from the facts For would have read.

Parameters

authenticated
Whether the visitor has signed in.
path
The canonical request path.
query
The raw query, carried into the sign-in link.
editorPath
The editor's own key, which is configuration.
The items, in reading order, with the one being shown marked as text.

Parameters

authenticated
Whether the visitor has signed in.
path
The canonical request path.
query
The raw query, carried into the sign-in link.
editorPath
The editor's own key, which is configuration.
The items the document's footer carries, which are the same on every page.
The layout the stored pages are served in writes these in a footer, and the shell writes the same document for its own views: a footer is where the two links every page carries belong, and the header is for where the visitor can go from here.

Http

Http.DisconnectGuard

Turns a client that left mid-write into a quiet end rather than an unhandled exception.
Registered inside UseExceptionHandler, because that handler logs an unhandled exception before it invokes its branch. A disconnect is not a failed request: the run or the page may still be working, and nothing could have been sent to the client anyway.

MethodUseDisconnectGuard(IApplicationBuilder app)

Adds the guard to the pipeline.

Parameters

app
The pipeline, after the exception handler and before the endpoints.

Http.MachineTrafficMetrics

Keeps machine traffic out of the HTTP request duration metrics.
The container's health check and Prometheus both ask on a timer; left in the histogram those requests read as visitor traffic and pull the duration buckets toward zero. Only the duration instrument is suppressed, because the active-request gauge measures the server rather than the site's traffic and these are real requests on it.

FieldHealthPath

The path the health probe answers on.

FieldScrapePath

The path Prometheus scrapes.

MethodSkipAsync(HttpContext context, RequestDelegate next)

Disables request duration metrics for a machine request, then continues the pipeline.

Parameters

context
The request being handled.
next
The rest of the pipeline.

Http.NotFound

Answers a URL that names no page with a 404 the caller can act on.

Http.PageUrls

Builds the URLs the shell links to, escaped for a URL rather than for HTML.
Every method returns a URL ready to be encoded once, by the HTML layer, at the attribute it is written into. Nothing here is HTML-encoded, and nothing returned is HTML-encoded.

MethodPage(PagePath)

The public URL of the page at path.

MethodEditor(PagePath path, string editorPath)

The editor page's URL for the page at path.

Parameters

path
The page to edit.
editorPath
The editor's own key, which is configuration rather than a constant.

MethodEditorCommand(PagePath path, string command, string editorPath)

The editor page's URL for a named command on the page at path.

Parameters

path
The page to edit.
command
The command the editor page should run.
editorPath
The editor's own key.

MethodEditorRevision(PagePath path, string hash, string editorPath)

The editor page's URL for one saved revision of the page at path.

Parameters

path
The page to read.
hash
The revision to show.
editorPath
The editor's own key.

MethodEditorDiff(PagePath path, string from, string to, string editorPath)

The editor page's URL comparing two saved revisions of the page at path.

Parameters

path
The page to compare.
from
The older revision.
to
The newer revision.
editorPath
The editor's own key.

MethodScrub(PagePath)

The scrub route for the page at path, which is the shell's.

Http.Redirect

Sends a redirect, encoding each part of the target with the type that understands it.

MethodTo(HttpContext context, int status, string target)

Sends target as the location of a redirect.

Parameters

context
The request being answered.
status
The redirect status to send.
target
A relative target, which may carry a query and a fragment, or an absolute URL.

MethodSeeOther(HttpContext, string)

Sends a POST result to a GET of target.

Http.ResponseWrite

Recognises a write that failed because the client or the response had already gone.
The exception handler logs an unhandled exception before it tries to write its error page. A response that has already started cannot take that page, and a client that has left cannot take anything, so both must be recognised before the handler sees them.

MethodIsDisconnect(HttpContext context, Exception exception)

Whether an exception is the response's own end rather than a fault.

Parameters

context
The request being answered.
exception
The exception the write raised.

Http.SecurityHeaders

The header set every response carries, and the one deliberate way to widen it.
A default set here cannot be forgotten by an endpoint, and reaches responses no endpoint owns, such as a routing 404 or 405. The headers are written when the response starts, so an endpoint that sets one first — or an exception handler that clears the response — is respected.

FieldContentSecurityPolicy

The name of the policy that varies by page.

PropertyDefault

The policy every response gets: no script at all.

PropertyWithScripts

The policy for a response that loads a same-origin script, and nothing else.

MethodApplyAsync(HttpContext, RequestDelegate)

Writes the header set for a response that has not set one of its own.

MethodAllowScripts(HttpContext context)

Widens this response's policy to allow same-origin scripts.

Parameters

context
The response that is about to load a script.

MethodNoStore(HttpContext context)

Marks the response as one no cache may keep.

Parameters

context
The response to mark.

MethodNoStoreIfAbsent(HttpContext context)

Marks the response as uncacheable, unless a view already asked for something stronger.

Parameters

context
The response to mark.

MethodIsOwned(string name)

Whether the shell writes this header itself, so a page may not set it.
SimpleContext lets a page set any X- name, which includes several of these; without this a page could blank its own nosniff.

Parameters

name
The header name to test.

Returns

True when the shell owns the header.

Http.ShellCookies

The cookies the shell owns, and the one place their names are written.
The names are one character each because a browser's cookie pane stops being self-explanatory. They are defined here so the authentication registration, the page session and the request snapshot a page sees cannot drift: a page is never handed one of these, and never sets one.

FieldAuthentication

The authentication ticket's key.

FieldAntiforgery

The antiforgery pair's cookie.

FieldSession

The page session's id.

MethodIsOwned(string name)

Whether name belongs to the shell rather than to a page.

Parameters

name
The cookie name to test.

Returns

True when the shell owns the cookie.

Logging

Logging.LogScope

The ambient facts every line written while the scope is open carries.

The formatter reads the fields when the entry is written, not when the scope is opened, so a value that only becomes known later - the signed-in account, a route value - is on every line after it and on no line before it, which is the truth.

The keys are the schema of the journal: anything naming something ends in Id, and the signed-in account is UserName. See docs/logging.md.

MethodSet(string name, object value)

Adds or replaces a field; a value that is not known adds nothing.

Parameters

name
The field's name, as it appears in the journal.
value
The value, or null when it is not known.

MethodGetEnumerator()

Inherited from IEnumerable`1.GetEnumerator.

MethodSystem.Collections.IEnumerable.GetEnumerator()

Inherited from IEnumerable.GetEnumerator.

Logging.RequestLogScope

Puts the request's ambient facts on every line written while it is answered.
Two middleware, because a fact cannot be put on a line before it is known: UseRequestLogScope opens the scope with what the request itself carries and UseRequestLogSubject adds the account and the route values once authentication and routing have run.

MethodUseRequestLogScope(IApplicationBuilder app)

Opens the scope for the request, with the exchange's own identity.
Registered ahead of the exception handler on purpose: the handler logs an unhandled exception from inside this scope, so that line names the request like every other line about it, and the error page it renders is written inside the scope too.

Parameters

app
The pipeline, before the exception handler.

MethodUseRequestLogSubject(IApplicationBuilder app)

Adds the account and the route's own ids, once both are known.

Parameters

app
The pipeline, after authentication and routing.

Metrics

Metrics.ChartEndpoint

Serves one panel's drawing on its own, for a link or a bookmark.

The addon, not the page's assembly line: the page embeds the same renderer's output and never asks this route for it. A URL names a panel, a start and a duration, and the drawing is a function of those three, so a link reproduces the chart it showed.

A malformed window is refused rather than defaulted: a hotlink is a claim about a period, and one that silently drew a different period would be a lie. The page's own ?duration= stays lenient, because that is navigation typed by hand.

MethodHandleAsync(HttpContext context, Metrics.Dashboard dashboard, TimeProvider time, CancellationToken cancellationToken)

Answers GET /admin/status/chart for the owner.

Parameters

context
The response being written.
dashboard
Builds the drawings, and holds the cache the page shares.
time
The clock a window without a start ends at.
cancellationToken
Aborted when the request is abandoned.

Metrics.ChartRenderer

Turns one panel and one window into one drawing.
This is the only code that runs a panel's queries and turns the answers into SVG, which is what lets the page embed a chart and the chart endpoint serve one: both call this and get the same bytes.

MethodChartRenderer(Metrics.IMetricsSource source, Metrics.MetricsOptions options)

Turns one panel and one window into one drawing.
This is the only code that runs a panel's queries and turns the answers into SVG, which is what lets the page embed a chart and the chart endpoint serve one: both call this and get the same bytes.

Parameters

source
Where the answers come from.
options
The zone the time labels are written in.

MethodRenderAsync(Metrics.Panel panel, Metrics.ChartWindow window, string titleHref, CancellationToken cancellationToken)

Draws one panel for one window.

Parameters

panel
The panel, whose chart kind decides the drawing.
window
The start and length every query is run over.
titleHref
Where the drawing's title links, or null when the drawing is already the page that link would open — which is what the chart endpoint passes.
cancellationToken
Aborted when the request is abandoned.

Returns

The drawing, or why it could not be drawn; never throws for a remote failure.

Metrics.ChartResult

One panel's drawing, or the reason there is none.

MethodChartResult(string Svg, string Reason)

One panel's drawing, or the reason there is none.

Parameters

Svg
The drawing, or null when a query failed.
Reason
Why a query failed, or null when the drawing was made.

PropertySvg

The drawing, or null when a query failed.

PropertyReason

Why a query failed, or null when the drawing was made.

Metrics.ChartWindow

One period a chart is drawn over: an explicit start and a length.
A window is a value, not "the last hour": the start is snapped down to the sample step, so the same start and length are the same query. A page's window ends at the current step, and a link's window is whatever it named — which is what lets a chart URL reproduce the picture it showed.

MethodChartWindow(DateTimeOffset Start, TimeSpan Length)

One period a chart is drawn over: an explicit start and a length.
A window is a value, not "the last hour": the start is snapped down to the sample step, so the same start and length are the same query. A page's window ends at the current step, and a link's window is whatever it named — which is what lets a chart URL reproduce the picture it showed.

Parameters

Start
The left edge, snapped to the step.
Length
How far the window reaches.

PropertyStart

The left edge, snapped to the step.

PropertyLength

How far the window reaches.

FieldDefaultToken

The token a request that names no window gets.
A day, not an hour: a day is long enough to show a trend and short enough to stay a useful number of samples, and it is what the page is opened to look at.

PropertyDefaultLength

The length a request that names no window gets.

PropertyTokens

The windows the nav offers, in the order it lists them.
A token is matched, never parsed: 1h and 3h are two windows to choose between, not a syntax for any length of time. A stale bookmark that names an unknown token gets the default rather than an error, because the page is opened by hand.

PropertyEnd

The right edge of the window.

PropertyStep

The spacing of the samples the window asks for.

PropertyRateRange

How long a rate averages over, as PromQL writes it: one step, so each drawn sample is the whole slice it stands for rather than a narrow reading of it.

MethodAt(DateTimeOffset start, TimeSpan length)

Builds a window from an explicit start and length, snapping the start to the step.

Parameters

start
The left edge the caller asked for.
length
How far the window reaches; it must be positive.

Exceptions

ArgumentOutOfRangeException
The length is zero or negative.

MethodFromToken(string token, DateTimeOffset now)

Builds the window a duration token names, ending at the current step.

Parameters

token
The token from the query string; null or unknown means the default.
now
The instant the window ends at, before snapping.

MethodTokenFor(string token)

The token that names the window being shown.

Parameters

token
The token from the query string; null or unknown means the default.

MethodLengthForToken(string token)

The length a token names, or the default when it names none.

Parameters

token
The token from the query string; null or unknown means the default.

MethodStepFor(TimeSpan length)

The sample spacing a length needs to stay under the sample target.

Parameters

length
How far the window reaches.

Metrics.ChartWindow.WindowToken

One window the nav offers.

MethodWindowToken(string Token, TimeSpan Length)

One window the nav offers.

Parameters

Token
The value carried in the duration query string, and the nav's label.
Length
How far back the queries reach.

PropertyToken

The value carried in the duration query string, and the nav's label.

PropertyLength

How far back the queries reach.

Metrics.Dashboard

Runs the catalogue's queries for one window and remembers the page for a few seconds.
The page is refreshed by a person and every view runs one range query per panel, so a refresh loop must not become a load test. Windows are cached by their snapped start and length, in a small bounded map: a link may name any start, and a route the owner can call must not grow a dictionary without a limit. A remote failure is a banner, never an exception, so the page still renders.

MethodDashboard(Metrics.ChartRenderer renderer, TimeProvider time, Metrics.MetricsOptions options, ILogger<Metrics.Dashboard> logger)

Runs the catalogue's queries for one window and remembers the page for a few seconds.
The page is refreshed by a person and every view runs one range query per panel, so a refresh loop must not become a load test. Windows are cached by their snapped start and length, in a small bounded map: a link may name any start, and a route the owner can call must not grow a dictionary without a limit. A remote failure is a banner, never an exception, so the page still renders.

Parameters

renderer
Draws one panel at a time.
time
The clock a cache entry's age is measured against.
options
How long an answer is reused and how many windows are kept.
logger
Where an incomplete page is explained.

MethodGetAsync(Metrics.ChartWindow window, CancellationToken cancellationToken)

Builds the page for one window, reusing the last one while it is still fresh.

Parameters

window
The start and length to draw.
cancellationToken
Aborted when the request is abandoned.

MethodHref(Metrics.Panel panel, Metrics.ChartWindow window)

The URL that draws one panel for the same window, for the figure's caption link.

Parameters

panel
The panel.
window
The window.

Metrics.IMetricsSource

Runs PromQL over a range and returns charts-ready series.

MethodQueryAsync(string query, DateTimeOffset from, DateTimeOffset to, TimeSpan step, CancellationToken cancellationToken)

Runs one query.

Parameters

query
The PromQL expression.
from
The start of the range.
to
The end of the range.
step
The spacing of the returned samples.
cancellationToken
Aborted when the request is abandoned.

Returns

The series, or why there are none; never throws for a remote failure.

Metrics.InstrumentKind

The three kinds of instrument the site registers.

FieldHistogram

A distribution over buckets; drawn as a heatmap.

FieldCounter

A monotonic count; drawn as a rate.

FieldGauge

A level at the moment it is read.

Metrics.MetricInstrument

One instrument a meter registers, as the catalogue and the drift test see it.

MethodMetricInstrument(string Name, Metrics.InstrumentKind Kind, string Unit)

One instrument a meter registers, as the catalogue and the drift test see it.

Parameters

Name
The instrument name, which is also its panel's id.
Kind
What sort of instrument it is, which decides how it is drawn.
Unit
The unit the instrument records, in OpenTelemetry's notation.

PropertyName

The instrument name, which is also its panel's id.

PropertyKind

What sort of instrument it is, which decides how it is drawn.

PropertyUnit

The unit the instrument records, in OpenTelemetry's notation.

Metrics.MetricsMatrix

The query answered with one series per labelled result.

MethodMetricsMatrix(IReadOnlyList<ChartSeries> Series)

The query answered with one series per labelled result.

Parameters

Series
The series, possibly empty when the query matched nothing.

PropertySeries

The series, possibly empty when the query matched nothing.

Metrics.MetricsOptions

Where the dashboard reads metrics from, how long it keeps an answer and how it labels time.
Every value comes from Metrics.

PropertyPrometheusUrl

The Prometheus base address; queries are appended to it.

PropertyTimeZone

The zone resolved once at startup.

PropertyQueryTimeout

How long one Prometheus query may take.

PropertyCacheFor

How long a built status page is reused before it is queried again.

PropertyMaxCachedWindows

How many window pages the cache keeps before the oldest is dropped.

MethodFromConfiguration(IConfiguration configuration)

Reads Metrics.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Metrics into the caller's report.

Parameters

reader
A reader opened on Metrics, which the caller completes.

Metrics.MetricsUnavailable

The query could not be answered.

MethodMetricsUnavailable(string Reason)

The query could not be answered.

Parameters

Reason
Text for the banner, written for the person reading the page.

PropertyReason

Text for the banner, written for the person reading the page.

Metrics.Panel

One chart on the status page.

PropertyId

The panel's id: the instrument's name, or a named id for a composed or Host panel.

PropertyGroup

The group the panel is listed under.

PropertyTitle

The heading the drawing carries.

PropertyDescription

A sentence saying what the chart shows, for the title's hover text and the drawing's description.

PropertyYTitle

What the value axis measures. A heatmap's is its bucket unit.

PropertyChart

How the panel is drawn.

PropertyQueries

The queries whose answers the drawing is made from.

PropertyCellUnit

What a heatmap's cells count, per second, for its legend and its hover text.

PropertyInstrumentName

The instrument the panel draws, or null for a panel that composes instruments or reads the framework's.

PropertySourceInstruments

The instruments a composed panel reads, when it owns none.

PropertyHostFamilies

The framework families a Host panel reads.

PropertyPartsOfAWhole

The label whose values partition one total, when the panel is a stacked area.

Metrics.PanelChart

How a panel is drawn.

FieldHeatmap

A distribution over buckets, drawn as a heatmap.

FieldLine

A value over time, one line per label.

FieldStackedArea

Parts of one total, stacked.

Metrics.PanelQuery

One PromQL expression a panel runs, and the name to give an anonymous series.

MethodPanelQuery(string Query, string Label)

One PromQL expression a panel runs, and the name to give an anonymous series.

Parameters

Query
The expression.
Label
The label a series without one takes.

PropertyQuery

The expression.

PropertyLabel

The label a series without one takes.

FieldRange

Where a rate names its averaging window. The renderer replaces it with the drawn window's step, so a sample averages over the same slice of time it stands for at any duration.

Metrics.PrometheusNames

The metric family names the Prometheus exporter writes for an instrument.
The exporter sanitises the dotted name to underscores and appends the unit where it names one: s becomes _seconds, By becomes _bytes, and a dimensionless 1 or an annotation such as {step} adds nothing. A histogram then carries _bucket, _count and _sum, and a counter carries _total. MetricNamesTests reads the live /metrics body and proves this mapping against the exporter, so a rename or a unit change fails a test rather than emptying a panel.

MethodFamily(Metrics.MetricInstrument instrument)

The family prefix an instrument is exported under, without a type suffix.

Parameters

instrument
The instrument.

MethodBuckets(Metrics.MetricInstrument instrument)

The family a histogram's buckets are exported under.

Parameters

instrument
The instrument.

MethodSum(Metrics.MetricInstrument instrument)

The family a histogram's observations sum to.

Parameters

instrument
The instrument.

MethodTotal(Metrics.MetricInstrument instrument)

The family a counter's total is exported under.

Parameters

instrument
The instrument.

Metrics.PrometheusSource

Talks to Prometheus' query_range API.
The response is parsed with small DTOs and a hand-written sample reader, because the values array mixes a number and a string, and the string is where NaN and the infinities hide.

MethodPrometheusSource(HttpClient http, ILogger<Metrics.PrometheusSource> logger, TimeSpan queryTimeout)

Creates a source over a client whose base address is the Prometheus origin.

Parameters

http
The client to send queries with.
logger
Records what a failed query actually failed with.
queryTimeout
The per-query deadline, from Metrics:QueryTimeoutSeconds.

MethodQueryAsync(string, DateTimeOffset, DateTimeOffset, TimeSpan, CancellationToken)

Runs one query.

Inherited from Metrics.IMetricsSource.QueryAsync.

Parameters

query
The PromQL expression.
from
The start of the range.
to
The end of the range.
step
The spacing of the returned samples.
cancellationToken
Aborted when the request is abandoned.

Returns

The series, or why there are none; never throws for a remote failure.

Metrics.QueryResult

What one query returned: data, or the reason there is none.
Failure is a value rather than an exception, because the status page is what gets opened when things are broken and must survive Prometheus being down.

Metrics.StatusCatalogue

The panels the status page draws, one per instrument and one per host question.

The catalogue is the only source of panels: Metrics.Dashboard holds no queries. Each entry names an instrument (or, in the Host group, the framework families it reads), and the chart kind follows the instrument's kind — a histogram is a heatmap, a counter is a line chart, a gauge is a line chart, and a counter whose labels partition one total is a stacked area. A panel may instead compose existing instruments when one question spans them, as the render chain does.

StatusCatalogueTests asserts every instrument has exactly one owning panel, that a composed panel names its sources, and that every family a query names is accounted for, which is what stops the page drifting from the instruments it is built from.

PropertyGroups

The groups, in the order the page lists them.

PropertyPanels

Every panel, in the order the page draws them.

MethodFind(string id)

Finds a panel by the id a link names.

Parameters

id
The panel id, which is the instrument name for an instrument panel.

Returns

The panel, or null when nothing has that id.

Metrics.StatusEndpoint

The owner-only dashboard: queries Prometheus and draws the answer as SVG charts.
The document around the body is Html.ShellDocument's, so the head, the sheet list, the site menu, the skip link, the landmark and the close cannot drift from the rest of the site. This type writes the heading, the window nav, the banner and one figure per panel, and nothing else.

MethodHostLine()

What the dashboard is the status of, in one line under the heading.
Each name links to the project it names, so the line says what the numbers are made of.

MethodHandleAsync(HttpContext context, Metrics.Dashboard dashboard, TimeProvider time, CancellationToken cancellationToken)

Answers GET /admin/status for the owner.

Parameters

context
The response being written.
dashboard
Builds the drawings for the window.
time
The clock the window ends at.
cancellationToken
Aborted when the request is abandoned.

Metrics.StatusEndpoint.StatusGroup

One group's panels, in catalogue order.

MethodStatusGroup(string, IReadOnlyList<Metrics.StatusPanel>)

One group's panels, in catalogue order.

Metrics.StatusPage

Everything the status endpoint needs to write the page.

MethodStatusPage(IReadOnlyList<Metrics.StatusPanel> Panels, string Banner)

Everything the status endpoint needs to write the page.

Parameters

Panels
The drawings, in catalogue order.
Banner
Why some are missing, or null when everything answered.

PropertyPanels

The drawings, in catalogue order.

PropertyBanner

Why some are missing, or null when everything answered.

Metrics.StatusPanel

One titled drawing on the status page.

MethodStatusPanel(Metrics.Panel Panel, string Svg)

One titled drawing on the status page.

Parameters

Panel
The catalogue entry it was drawn from.
Svg
The drawing; it is never null, because a panel with no data says so itself. Its title is the link that opens the same chart on its own.

PropertyPanel

The catalogue entry it was drawn from.

PropertySvg

The drawing; it is never null, because a panel with no data says so itself. Its title is the link that opens the same chart on its own.

Pages

Pages.BodyBudget

The body allowance one request's whole layout chain shares.
A layout wraps the page, so the chrome is part of the same response: handing each layer the whole allowance would let a chain buffer several times the configured maximum. The layer that runs out is the one named in the error.

MethodBodyBudget(int maxChars)

Creates the budget.

Parameters

maxChars
How much body the request may buffer before it is refused.

PropertyMaxChars

How much body one request may buffer.

PropertyRemaining

How much body this budget has left to give.
An embedded layer renders into a budget of this size, so its whole body fits.

MethodTryCharge(int chars)

Charges one write against the budget.

Parameters

chars
The length of the text about to be written.

Returns

Whether the write fits; nothing is charged when it does not.

Pages.BuildInfo

The commit this build was made from.

PropertyCurrent

The one build serving this process.

PropertyCommit

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

Inherited from IBuildInfo.Commit.

Pages.CompileOptions

Bounds what one compilation may cost.
Roslyn honours a cancellation token between operations rather than inside one, so the timeout is a coarse bound on a pathological template, not a hard one. The slot count is the part that holds. Every value comes from Pages:Compile.

PropertySlots

Compiles allowed to run at once.

PropertyTimeoutSeconds

The budget for one compile, in seconds.
May be a fraction of a second, down to MinimumTimeoutSeconds.

PropertyTimeout

The budget as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Compile.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Compile into the caller's report.

Parameters

reader
A reader opened on Pages:Compile, which the caller completes.

Pages.EditorPaths

Reads the editor's key, the one policy every link to the editor is built from.
The key is configuration (Pages:Editor:Key) rather than a constant, so a shell view that hard-codes it sends the owner to a page that is no longer the editor. The value is required, so a request without one is a wiring mistake rather than a second spelling of the key.

MethodOf(IServiceProvider services)

The editor's key for this request.

Parameters

services
The request's services.

Exceptions

InvalidOperationException
The request has no editor key.

Pages.EmptyHttpFetchStream

A stream-shaped failure value for a request that received no usable response body.

MethodEmptyHttpFetchStream(HttpFetchFailure, Action<HttpFetchStream>)

A stream-shaped failure value for a request that received no usable response body.

PropertyStatus

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

Inherited from HttpFetchStream.Status.

PropertyHeaders

The response headers exposed by the host.

Inherited from HttpFetchStream.Headers.

PropertyFailure

Why the request or stream ended, or None.

Inherited from HttpFetchStream.Failure.

PropertyTruncated

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

Inherited from HttpFetchStream.Truncated.

MethodReadLineAsync()

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

Inherited from HttpFetchStream.ReadLineAsync.

Returns

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

MethodCloseAsync()

Closes the response and releases its connection.

Inherited from HttpFetchStream.CloseAsync.

Returns

A task that completes when the response is closed.

Pages.IOutboundCredential

A header that may be attached to some of an outbound request's hops.

The one thing Pages.OutboundFetcher asks of a credential: for this hop, is there a header, and what is it? Where a credential may go is the credential's own rule, so the page's rule and the view's are stated once each rather than re-implemented by every caller — and there is exactly one place that puts a header on a message, which is what keeps it off a redirect to another host.

HeaderValue reads the secret, so only the fetcher calls it. Name is what belongs in a log line.

PropertyName

A name safe to log, which never contains the value.

PropertyHeader

The request header the value is sent in.

PropertyHeaderValue

The header value: the scheme and one space, then the secret.

MethodAppliesTo(Uri uri)

Whether this credential may be attached to a request for uri.

Parameters

uri
The request or redirect target.

Pages.IPageBatchStore

Writes a whole import in one transaction: all of it, or none of it.

MethodSaveBatchAsync(IReadOnlyList<Pages.PageBatchSave> pages, CancellationToken cancellationToken)

Stores every page in one transaction.

Parameters

pages
The pages to store, in key order.
cancellationToken
Cancels the write.

Returns

Committed, or the pages whose merged state would overflow a cap. A refusal writes nothing.

Pages.IPageBodySink

The response a streaming page writes into.
The first StartAsync is the commit point: headers are final from then on and the body is sent as it is written.

MethodStartAsync(PageResponse response, CancellationToken cancellationToken)

Applies and starts the response, making the headers final.

Parameters

response
What the page asked the response to be.
cancellationToken
Cancels the start.

MethodWriteAsync(ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken)

Writes one flushed piece of the body.

Parameters

bytes
The UTF-8 body to write.
cancellationToken
Cancels the write.

Pages.IPageFetcher

The seam Pages.PageHttpFetch calls for an outbound fetch.
A test replaces this to prove the page contract without a socket, and the integration suite replaces it to prove the wiring; the real implementation is the only thing that opens one.

MethodFetchAsync(HttpFetchRequest request, string pagePath, CancellationToken aborted, CancellationToken deadline)

Makes one bounded outbound request.
The two tokens travel separately rather than linked, because a refusal has to say which one fired: the visitor leaving is Aborted, and the render running out of budget is Timeout.

Parameters

request
The page's request.
pagePath
The page's key, for the metric and log tags.
aborted
Cancelled when the visitor went away.
deadline
Cancelled when the render's budget ran out.

Returns

The response; a failure is reported in the value, not thrown.

MethodStreamAsync(HttpFetchRequest request, string pagePath, CancellationToken aborted, CancellationToken deadline)

Opens one bounded outbound response stream.

Parameters

request
The page's request.
pagePath
The page's key, for the metric and log tags.
aborted
Cancelled when the visitor went away.
deadline
Cancelled when the render or stream budget ran out.

Returns

The stream; failures are reported through its values.

Pages.IPageReadStore

The read-only seam a page's catalog reads through.

It is a seam of its own rather than Pages.IPageStore because that one is scoped to the request's StorageDbContext, and a page's task deliberately outlives the request. Every call here owns its context, as Pages.IPageStateStore does.

It answers with small records and never with a PagePath: normalising a key and deciding what a listing reports is the capability's job, so a page never meets a core type. There is no write member, and no member that names an image, a symbol or an archive.

MethodListLibrariesAsync(CancellationToken cancellationToken)

Lists the live library pages, ordered by key.
This is the compiler's read, not a page's: a library is an input to every page that names it, so a row cap here would stop those pages compiling rather than shorten a listing.

Parameters

cancellationToken
Cancels the read.

Returns

Every live library head, in ordinal key order.

MethodListAsync(string prefix, int limit, CancellationToken cancellationToken)

Lists the heads under a prefix, ordered by key.

Parameters

prefix
The canonical subtree prefix; / is the whole store.
limit
The most rows to select, as a limit in the statement.
cancellationToken
Cancels the read.

Returns

At most limit heads, in ordinal key order.

MethodGetHeadAsync(string key, CancellationToken cancellationToken)

Reads one head, which is how a caller learns what a key holds.
It is one row rather than a listing of the key's subtree: a caller that needs a page's kind before it can decide anything must not be given its children as a side effect.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The head, a tombstone's included, or null when no page has that key.

MethodGetSourceAsync(string key, CancellationToken cancellationToken)

Reads a live page's template.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The template, or null when no live page has that key.

MethodListRevisionsAsync(string key, CancellationToken cancellationToken)

Lists one page's history, newest first.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The page's revisions, including those of a tombstone; empty for an unknown key.

MethodGetRevisionSourceAsync(string key, string hash, CancellationToken cancellationToken)

Reads one revision's template, by both of its handles.

Parameters

key
The canonical key the revision belongs to.
hash
The revision's hash.
cancellationToken
Cancels the read.

Returns

The template, or null when that page has no such revision.

Pages.IPageRevisionStore

Stores one page revision, on a context of its own.
A page's task can outlive the request that started it, so a save made from inside a render cannot go through Pages.IPageStore: that one is scoped to the request's StorageDbContext, which may already be disposed by the time the write lands. The implementation opens its context per save, for the reason Pages.SqlitePageStateStore does.

MethodSaveAsync(Pages.PageTemplate revision, CancellationToken cancellationToken)

Inserts the revision and moves the page's head to it, in one transaction.

Parameters

revision
The revision, already built with its id, hash and image.
cancellationToken
Cancels the write.

Returns

The revision that was stored. It is the argument unless another writer took its revision id, in which case it is the retry — so a caller that reports a hash reports the stored one.

MethodTrySaveAsync(Pages.PageTemplate revision, string expectedHash, CancellationToken cancellationToken)

Inserts the revision and moves the head to it, only while the head still matches.

Parameters

revision
The revision, already built with its id, hash and image.
expectedHash
The hash the caller saw as the head.
cancellationToken
Cancels the write.

Returns

false when the head is missing, tombstoned or another hash, so nothing was written.

Pages.IPageSessionStore

The session operations the shell uses for one visitor's state.
Values cross this seam as JSON text, because presence and value are decided by one SQL read and the store has no business knowing a page's types. The per-value cap is checked by the scope; the per-session key count and byte total are enforced in the same statement as the write.

MethodFindAsync(string sessionId, CancellationToken cancellationToken)

Finds a session row.

Parameters

sessionId
The id from the visitor's cookie.
cancellationToken
Cancels the read.

Returns

The row, or null when the id names no live session.

MethodEnsureAsync(string sessionId, string account, CancellationToken cancellationToken)

Mints a session row, evicting at the live-session cap when it has to.

Parameters

sessionId
The id to mint.
account
The normalised account name, or null.
cancellationToken
Cancels the write.

Returns

Whether the row exists afterwards. A mint is refused only when the table is at its cap and nothing at all can be evicted.

MethodTouchAsync(string sessionId, CancellationToken cancellationToken)

Slides a session's idle timer.

Parameters

sessionId
The id that was touched.
cancellationToken
Cancels the write.

MethodDeleteAsync(string sessionId, CancellationToken cancellationToken)

Deletes a session and every value it holds.

Parameters

sessionId
The id to delete.
cancellationToken
Cancels the write.

Returns

Whether a row was deleted.

MethodGetValueAsync(string sessionId, string pagePath, string key, CancellationToken cancellationToken)

Reads one value.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to read.
cancellationToken
Cancels the read.

Returns

The stored JSON, or null when the key is absent.

MethodSetValueAsync(string sessionId, string pagePath, string key, string value, Pages.PageSessionCaps caps, CancellationToken cancellationToken)

Writes one value, applying every per-session cap in the same statement.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to write.
value
The value as JSON.
caps
The caps this visitor's session obeys.
cancellationToken
Cancels the write.

Exceptions

ArgumentException
A cap was hit, or the session no longer exists.

MethodDeleteValueAsync(string sessionId, string pagePath, string key, CancellationToken cancellationToken)

Removes one value.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to remove.
cancellationToken
Cancels the write.

Returns

Whether the key existed.

MethodListKeysAsync(string sessionId, string pagePath, CancellationToken cancellationToken)

Lists one page's keys.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key whose keys are listed.
cancellationToken
Cancels the read.

Returns

The keys, in ordinal order.

MethodListAllKeysAsync(string sessionId, CancellationToken cancellationToken)

Lists every page and key a session holds.

Parameters

sessionId
The visitor's session.
cancellationToken
Cancels the read.

Returns

The pairs, ordered by page and then key.

MethodRemoveExpiredAsync(CancellationToken cancellationToken)

Removes expired sessions, and trims the table to its live-session cap when it is over.

Parameters

cancellationToken
Cancels the sweep.

Returns

What the sweep removed, by kind.

Pages.IPageStateStore

The path-parameterised storage operations the shell uses for one page's state.
Values cross this seam as JSON text, because presence and value are decided by one SQL read and the store has no business knowing a page's types. Caps that need no other row are enforced here; the per-page caps are enforced in the same statement as the write.

MethodGetValueAsync(PagePath path, string key, CancellationToken cancellationToken)

Reads one value.

Parameters

path
The page whose state is read.
key
The key to read.
cancellationToken
Cancels the read.

Returns

The stored JSON, or null when the key is absent.

MethodSetValueAsync(PagePath path, string key, string value, CancellationToken cancellationToken)

Writes one value, applying every per-page cap in the same statement.

Parameters

path
The page whose state is written.
key
The key to write.
value
The value as JSON.
cancellationToken
Cancels the write.

Exceptions

ArgumentException
A cap was hit, or the page is no longer live.

MethodDeleteValueAsync(PagePath path, string key, CancellationToken cancellationToken)

Removes one key.

Parameters

path
The page whose state is written.
key
The key to remove.
cancellationToken
Cancels the write.

Returns

Whether the key existed.

MethodListKeysAsync(PagePath path, CancellationToken cancellationToken)

Lists a page's keys.

Parameters

path
The page whose keys are listed.
cancellationToken
Cancels the read.

Returns

The keys, in ordinal order.

MethodGetValuesAsync(PagePath path, CancellationToken cancellationToken)

Reads every key and value a page holds.

Parameters

path
The page whose state is read.
cancellationToken
Cancels the read.

Returns

The values, in ordinal key order; empty when the page has no state.

Pages.IPageStore

Stores page templates and the image built from each one.

MethodGetPageAsync(PagePath path, CancellationToken cancellationToken)

Reads a page's template and, when it has one, the stored image built from it.

Parameters

path
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The stored page, or null when no page has that key.

MethodListPagesAsync(CancellationToken cancellationToken)

Lists every page, live and deleted, with the state of its current image.
The state is judged against the running build, so a page whose image came from an earlier one says so: after a deploy that is every page, until each is next requested.

Parameters

cancellationToken
Cancels the read.

Returns

Every page, ordered by key.

MethodGetSourceAsync(PagePath path, CancellationToken cancellationToken)

Reads a live page's template text only, without the image stored beside it.
An export needs source and nothing else, and loading a page's assembly into memory to copy its text out of it would be wasted work.

Parameters

path
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The stored template, or null when no live page has that key.

MethodSavePageAsync(Pages.PageTemplate template, CancellationToken cancellationToken)

Creates or replaces a page's template and image in a single write.

Parameters

template
The page to store.
cancellationToken
Cancels the write.

MethodAdoptSeedAsync(PagePath path, string seedHash, CancellationToken cancellationToken)

Records the shipped seed as installed, without storing a revision.

Parameters

path
The canonical key.
seedHash
The hash of the seed the page's content already equals.
cancellationToken
Cancels the write.

Returns

True when the row recorded the seed; false when the page is missing, deleted or its content is no longer exactly the seed, so the caller must read it again.

MethodTrySavePageAsync(Pages.PageTemplate template, string expectedHash, CancellationToken cancellationToken)

Saves a revision only when the current live head still has the expected hash.

Parameters

template
The new template and the image built from it.
expectedHash
The current head hash the caller read.
cancellationToken
Cancels the write.

Returns

False when the page is missing, deleted or has changed since it was read.

MethodTrySetImageAsync(string revisionId, string expectedTemplate, Pages.PageImage image, CancellationToken cancellationToken)

Stores an image only while the page still holds the template it was built from.

Parameters

revisionId
The revision the image belongs to.
expectedTemplate
The template the image was built from.
image
The image to store.
cancellationToken
Cancels the write.

Returns

true when the result was stored; false when the page changed or disappeared while it compiled, so the caller must read it again.

MethodScrubPageAsync(PagePath path, CancellationToken cancellationToken)

Removes a deleted page head and all of its revisions.

Parameters

path
The canonical key of a deleted page.
cancellationToken
Cancels the cleanup.

Returns

true when a deleted head was scrubbed; otherwise, false.

Pages.IRenderBoundCapability

A capability the render can stop.
Two things end a capability call early: the render's deadline, and the render being given up on. Both come from the shell, never from the page, because the SDK has no abandonment member (`pages-page-io-is-async`).

MethodAttachDeadline(CancellationToken deadline)

Gives the capability the render's deadline.

Parameters

deadline
The deadline's token; it outlives this use of it.

MethodAbandon()

Stops accepting work, because the render was given up on.

Pages.IRenderBoundPageStorage

Page storage the render can stop.
The handle a page holds is only IPageStorage; this is the shell's view of the same object, with the deadline and abandonment the SDK deliberately does not expose (`pages-page-io-is-async`).

Pages.IRenderLifetimeAware

A capability that owns resources until its render lifetime ends.

MethodAttachLifetime(Pages.RenderLifetime lifetime)

Attaches the render lifetime and its asynchronous cleanup boundary.

Parameters

lifetime
The render lifetime that owns this capability.

Pages.OutboundFetcher

Makes a bounded, text-only outbound HTTP request.

The mechanics behind both Pages.IPageFetcher and the assistant's fetch tool. Every refusal is a value rather than an exception, so a caller can fall back without a try. Nothing here logs a query, a header or a body: the host is named, and the caller's own log lines are the place for anything more specific.

There is no allow-list: any absolute http or https URL is reachable, and the caller decides whether that is acceptable for its audience (`pages-outbound-fetch`). The remaining guards are about shape rather than destination — no credentials in the URL, no fragment, no cookies, no automatic redirects, and a redirect hop is held to the same scheme rule before any connection is made.

MethodOutboundFetcher(IHttpClientFactory, Pages.PageFetchOptions, ILogger<Pages.OutboundFetcher>)

Makes a bounded, text-only outbound HTTP request.

The mechanics behind both Pages.IPageFetcher and the assistant's fetch tool. Every refusal is a value rather than an exception, so a caller can fall back without a try. Nothing here logs a query, a header or a body: the host is named, and the caller's own log lines are the place for anything more specific.

There is no allow-list: any absolute http or https URL is reachable, and the caller decides whether that is acceptable for its audience (`pages-outbound-fetch`). The remaining guards are about shape rather than destination — no credentials in the URL, no fragment, no cookies, no automatic redirects, and a redirect hop is held to the same scheme rule before any connection is made.

FieldClientName

The named client whose handler the host pools.

MethodFetchAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, CancellationToken aborted, CancellationToken deadline)

Performs one request, bounded by aborted and deadline.
A caller with no credential, which is every assistant request.

Parameters

request
The request to make.
caller
Who asked, for the log line: a page key or a tool name.
origin
Whether page code or the assistant asked, for the User-Agent.
aborted
Cancelled when the caller gives up.
deadline
Cancelled when the caller's budget expires.

MethodFetchAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, Pages.IOutboundCredential credential, CancellationToken aborted, CancellationToken deadline)

Performs one request, attaching credential only where it applies.

Parameters

request
The request to make.
caller
Who asked, for the log line: a page key or a tool name.
origin
Whether page code or the assistant asked, for the User-Agent.
credential
A credential to attach where it applies, or null for none.
aborted
Cancelled when the caller gives up.
deadline
Cancelled when the caller's budget expires.

Returns

The response as a page reads it: text, and the headers a page may see.

MethodFetchResponseAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, Pages.IOutboundCredential credential, CancellationToken aborted, CancellationToken deadline)

Performs one request and answers the transport's own result.

Parameters

request
The request to make.
caller
Who asked, for the log line: a page key or a tool name.
origin
Whether page code or the assistant asked, for the User-Agent.
credential
A credential to attach where it applies, or null for none.
aborted
Cancelled when the caller gives up.
deadline
Cancelled when the caller's budget expires.

Returns

Every header, the body's bytes and the hops taken, for a caller that wants the response itself.

MethodStreamAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, Pages.IOutboundCredential credential, Action<HttpFetchStream> aborted, CancellationToken deadline, CancellationToken onClosed)

Opens a bounded text stream for one request.

Parameters

request
The request to make.
caller
Who asked, for the log line.
origin
Whether page code or the assistant asked, for the User-Agent.
credential
A credential to attach where it applies, or null for none.
aborted
Cancelled when the caller gives up.
deadline
Cancelled when the caller's lifetime ends.
onClosed
Records the completed stream.

Pages.OutboundHttpFetchStream

Reads one outbound response as bounded text lines.

PropertyStatus

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

Inherited from HttpFetchStream.Status.

PropertyHeaders

The response headers exposed by the host.

Inherited from HttpFetchStream.Headers.

PropertyFailure

Why the request or stream ended, or None.

Inherited from HttpFetchStream.Failure.

PropertyTruncated

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

Inherited from HttpFetchStream.Truncated.

MethodReadLineAsync()

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

Inherited from HttpFetchStream.ReadLineAsync.

Returns

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

MethodCloseAsync()

Closes the response and releases its connection.

Inherited from HttpFetchStream.CloseAsync.

Returns

A task that completes when the response is closed.

Pages.OutboundOrigin

Who asked for an outbound request, for its User-Agent.

FieldPage

Stored page code calling IHttpFetch.

FieldAssistant

The assistant's fetch tool or its provider request.

Pages.OutboundRedirect

One redirect an outbound request followed.

MethodOutboundRedirect(int Status, string Location)

One redirect an outbound request followed.

Parameters

Status
The status that sent the request on.
Location
Where it was sent, as the response named it.

PropertyStatus

The status that sent the request on.

PropertyLocation

Where it was sent, as the response named it.

Pages.OutboundResponse

What one outbound request actually produced.

The transport's own answer, and the one shape both callers read. HttpFetchResponse is the page's projection of it — allow-listed headers, text decoded by the declared charset — because a page wants text and a *view* of the site wants the response exactly as it was served: every header, the body's own bytes, and the hops it took to get there.

A caller that follows redirects gets the last response and the hops beside it, so a `302` to /login cannot look like a page that renders a sign-in form.

MethodOutboundResponse(int Status, IReadOnlyDictionary<string, string> Headers, byte[] Body, HttpFetchFailure Failure, bool Truncated, IReadOnlyList<Pages.OutboundRedirect> Redirects)

What one outbound request actually produced.

The transport's own answer, and the one shape both callers read. HttpFetchResponse is the page's projection of it — allow-listed headers, text decoded by the declared charset — because a page wants text and a *view* of the site wants the response exactly as it was served: every header, the body's own bytes, and the hops it took to get there.

A caller that follows redirects gets the last response and the hops beside it, so a `302` to /login cannot look like a page that renders a sign-in form.

Parameters

Status
The final response's status, or 0 when no response arrived.
Headers
Every response header, from the response and its content.
Body
The body's bytes, up to the configured response cap.
Failure
Why the fetch failed, or None.
Truncated
Whether the body hit the host's response cap.
Redirects
Every hop that was followed, in order, oldest first.

PropertyStatus

The final response's status, or 0 when no response arrived.

PropertyHeaders

Every response header, from the response and its content.

PropertyBody

The body's bytes, up to the configured response cap.

PropertyFailure

Why the fetch failed, or None.

PropertyTruncated

Whether the body hit the host's response cap.

PropertyRedirects

Every hop that was followed, in order, oldest first.

Pages.OutboundUserAgent

Builds the short User-Agent every outbound request carries.
The host, the origin and the contact address let a remote service see who is calling and how to reach the owner, without a version or anything ambient. The host sets it after a page's own headers, so a page cannot claim to be a different client.

FieldHost

The site's hostname, which identifies the caller.

FieldContact

The owner's address, which a remote service can use to make contact.

MethodUserAgent(Pages.OutboundOrigin origin)

The value sent for one origin.

Parameters

origin
Whether page code or the assistant asked.

Pages.PageAssetMap

The live assets one request may link by version, loaded at most once per request.

The map is the live heads whose verdict is false, keyed by a page key and holding the revision hash. It is read once per request: a page chooses its sheets while it runs, so the shell cannot know the set in advance, and ctx.AssetUrl cannot be asynchronous.

A stale entry is harmless. The hash still names a retained revision, so an older URL still serves the older bytes; the next request reads the newer head.

PropertyEmpty

The map a render with no readable store links against: every link stays as written.

MethodForRequestAsync(HttpContext context, Pages.IPageReadStore store, int limit, CancellationToken cancellationToken)

Reads the map once for a request.

Parameters

context
The request whose items cache the map.
store
Where the heads are read.
limit
The row cap, from Pages:Read.
cancellationToken
Cancels the read.

MethodLoadAsync(Pages.IPageReadStore store, int limit, CancellationToken cancellationToken)

Reads the live, no-code heads.

Parameters

store
Where the heads are read.
limit
The most rows to read.
cancellationToken
Cancels the read.

MethodResolve(IReadOnlyDictionary<string, string> map, string href)

Adds the revision hash to a site-relative link when its page is a live asset.
Only a bare site-relative path is touched. A query, a fragment, an absolute or protocol-relative URL, and any key that is not a live asset are all returned as written.

Parameters

map
The request's asset map.
href
The link as the page or view wrote it.

Returns

The versioned URL, or the link unchanged.

Pages.PageAssetPolicy

Decides what a revision's kind means for the response.
A page with no code is a complete representation: nothing the shell could inject belongs in it, so its response is its source and a URL naming one revision may promise never to change. A page with code is never pinned; it may keep state or vary by visitor. A library and a worker are not representations at all: the first is compiled into the pages that name it, the second is started by a page, and neither has a URL.

MethodIsAsset(PageKind? kind)

Whether a revision is an asset: it has no code.

Parameters

kind
The revision's kind; null means never judged.

MethodIsLibrary(PageKind? kind)

Whether a revision is a library: it is compiled into other pages and never served.

Parameters

kind
The revision's kind; null means never judged.

MethodIsWorker(PageKind? kind)

Whether a revision is a worker: a page starts it and no URL answers for it.

Parameters

kind
The revision's kind; null means never judged.

MethodIsServed(PageKind? kind)

Whether a URL may answer with this revision at all.
An unjudged revision is served, because judging it is what the first request does. This is the question the endpoint and the renderer ask, so a new kind that is not a representation cannot be served by forgetting one of them.

Parameters

kind
The revision's kind; null means never judged.

Pages.PageAssetSeeder

Installs the pages the shell ships with into a store that is missing them.

MethodSeedAsync(Pages.IPageStore pages, Pages.PageSeeds seeds, CancellationToken cancellationToken)

Installs the seeds a store is missing.
A key the store already has is left alone, whatever its source says: an edit survives a restart, and a tombstone stays a tombstone. A create is the one automatic seed write, so it records the seed's hash as the page's anchor.

Parameters

pages
The store to seed.
seeds
The pack this release ships.
cancellationToken
Bounds the reads and the writes.

MethodSeedPaths()

The page keys of the pack this build carries, in seeding order.

Pages.PageBatchResult

What a batch did.

MethodPageBatchResult(IReadOnlyList<PagePath> Refused)

What a batch did.

Parameters

Refused
The pages whose merged state would not fit; empty when the batch committed.

PropertyRefused

The pages whose merged state would not fit; empty when the batch committed.

PropertyCommitted

A result for a batch that stored every page.

PropertyIsCommitted

Whether every page in the batch is stored.

Pages.PageBatchSave

One page of a batch: the revision to store and the state to merge with what it holds.

MethodPageBatchSave(Pages.PageTemplate Template, IReadOnlyList<Pages.PageStateValue> State)

One page of a batch: the revision to store and the state to merge with what it holds.

Parameters

Template
The revision, already built with a fresh id, timestamp and hash.
State
The archive's state values; keys the page already has that these do not name are kept.

PropertyTemplate

The revision, already built with a fresh id, timestamp and hash.

PropertyState

The archive's state values; keys the page already has that these do not name are kept.

Pages.PageBody

The body one layer writes, and its way onto the wire.

The buffer, the lock that guards it, the shared budget, the commit and the abandonment flag are one object because they only make sense together: a page's task can still be running after the render gave up on it, so every write and the read that shapes the response happen under one gate, and an abandoned page finds that gate closed rather than racing the response it no longer owns.

Whether a stream is allowed at all is the layer's question: the refusal names the page and its remedy, so those messages stay on the context, and this type assumes the caller has checked CanStream.

MethodPageBody(StringWriter writer, PagePath path, Pages.BodyBudget budget, Pages.PageCommitState commit, Pages.IPageBodySink sink, CancellationToken aborted)

Creates one layer's body.

Parameters

writer
The buffer the body is written to.
path
The layer's own key, used when a write overruns the budget.
budget
The allowance the whole chain shares.
commit
Whether this layer has committed, shared with the capabilities.
sink
Where a flushing layer writes, or null when it cannot stream.
aborted
The token from the request being served.

PropertyIsCommitted

Whether the first flush has committed the response.

PropertyCanStream

Whether this layer has somewhere to stream to at all.

MethodAttachLifetime(Pages.RenderLifetime lifetime)

Gives the body the render's lifetime, so its I/O and its stream share one clock.

Parameters

lifetime
The lifetime the renderer opened for this request.

MethodAbandon()

Stops the layer writing, once its render has been given up on.
The page cannot be stopped, so this is what keeps it from filling the buffer — or racing the response — after the site has answered without it.

MethodWrite(string text)

Appends one piece of the body, charging it to the shared budget.

Parameters

text
The text to append; it is already escaped as the caller intended.

Exceptions

InvalidOperationException
The write overran the budget.

MethodGetText()

The body written so far.

MethodMintOnce(ref string slot, Func<string> create)

Reads or creates a value once, and never after the render was abandoned.
The antiforgery token is the only caller, and it is minted here because the gate is here: a token minted after the response has gone would leave a cookie nothing can verify.

Parameters

slot
Where the created value is kept, so a second read hands out the first.
create
Creates the value.

Returns

The value, or empty once the render has been abandoned.

MethodFlushAsync(PageResponse response)

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

Parameters

response
What the layer asked the response to be.

MethodCompleteAsync()

Writes whatever the layer left buffered after its last flush.
Only a committed response has a body to complete; a buffered one is shaped from the context by the endpoint. A disconnect or a deadline that fires during this last write is the response ending, not a page fault.

Pages.PageBodySink

The one response sink a streaming page writes into.

MethodPageBodySink(HttpContext, Pages.PageEnvironment, Pages.PageSessionRequest)

The one response sink a streaming page writes into.

MethodStartAsync(PageResponse, CancellationToken)

Applies and starts the response, making the headers final.

Inherited from Pages.IPageBodySink.StartAsync.

Parameters

response
What the page asked the response to be.
cancellationToken
Cancels the start.

MethodWriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Writes one flushed piece of the body.

Inherited from Pages.IPageBodySink.WriteAsync.

Parameters

bytes
The UTF-8 body to write.
cancellationToken
Cancels the write.

Pages.PageBudget

The process-wide limits on page work, shared by every request.
It is a singleton on purpose: a per-request semaphore would limit nothing. Waiting for a render slot is asynchronous, so a queued request holds no thread while it waits.

FieldMinimumTimeoutSeconds

The smallest budget a configuration may ask for, in seconds.
A budget of zero would switch the limit off rather than tighten it, so a value below the floor is clamped rather than honoured. The floor is not a whole second: the deadline is honoured in milliseconds, so an operator who wants a tighter bound than the default can ask for one.

MethodPageBudget(Pages.RenderOptions render, Pages.CompileOptions compile, Pages.StreamOptions stream)

Creates the limits from the configured options.

Parameters

render
The render limits.
compile
The compile limits.
stream
The stream limits.

PropertyRenderOptions

The render limits.

PropertyCompileOptions

The compile limits.

PropertyStreamOptions

The stream limits.

MethodDescribeSeconds(TimeSpan budget)

Describes a budget as the number of seconds a message shows.
A budget may be a fraction of a second, so a message must not print it as a whole number, and it must not pick up a decimal separator from the server's locale either.

Parameters

budget
The budget to describe.

Returns

The seconds without trailing zeros, in the invariant culture.

PropertyRenderSlots

Renders allowed to run at once.

PropertyCompileSlots

Compiles allowed to run at once.

PropertyStreamSlots

Committed streams allowed to be open at once.

MethodDispose()

Inherited from IDisposable.Dispose.

Pages.PageCapabilities

The registry a page reads its optional capabilities from.
Built while a layer is being constructed and handed to the page as the read-only IPageCapabilities, so nothing page code can name can add or replace a capability the host decided on.

MethodAdd<T>(T capability)

Registers a capability under the interface the page asks for.

Type parameters

T
The capability interface.

Parameters

capability
The implementation; it may not be null.

Returns

This registry, so the layer can register its capabilities in one expression.

Exceptions

InvalidOperationException
The capability is already registered.

MethodTryGet<T>(ref T)

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

Inherited from IPageCapabilities.TryGet<T>.

Parameters

capability
The implementation, when this render offers the capability.

Returns

Whether this render offers the capability.

MethodAttachLifetime(Pages.RenderLifetime lifetime)

Gives every bound capability the render's deadline and resource lifetime.

Parameters

lifetime
The render lifetime to attach.

MethodAttachDeadline(CancellationToken deadline)

Gives every bound capability the render's deadline.

Parameters

deadline
The deadline's token.

MethodAbandon()

Stops every bound capability, because the render was given up on.

Pages.PageCatalogScope

One layer's IPageCatalog, bound to that render.

It is offered to every layer, so a layout may read the store as well as a page may. There is no gate: the read answers for whoever the calling page answers for, and a page that wants its listing or its source private writes the ordinary ctx.User guard in its own source.

The shell links are the list the endpoint built once for this request, so every layer of one render sees one answer and the sign-in link carries the visitor's way back. A worker's list is empty: it has no request and no visitor.

The only refusals are about the call itself. An argument that cannot name anything is an ArgumentException, because that is a page bug; an abandoned render is an InvalidOperationException; and a cap is an InvalidOperationException that names the setting rather than a truncated answer.

One layer's IPageCatalog, bound to that render.

It is offered to every layer, so a layout may read the store as well as a page may. There is no gate: the read answers for whoever the calling page answers for, and a page that wants its listing or its source private writes the ordinary ctx.User guard in its own source.

The shell links are the list the endpoint built once for this request, so every layer of one render sees one answer and the sign-in link carries the visitor's way back. A worker's list is empty: it has no request and no visitor.

The only refusals are about the call itself. An argument that cannot name anything is an ArgumentException, because that is a page bug; an abandoned render is an InvalidOperationException; and a cap is an InvalidOperationException that names the setting rather than a truncated answer.

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

Inherited from IPageCatalog.ShellLinks.

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)

Lists the heads of the store, under a prefix.

Inherited from IPageCatalog.ListAsync.

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)

Reads a live page's template.

Inherited from IPageCatalog.ReadAsync.

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)

Lists one page's history, newest first.

Inherited from IPageCatalog.RevisionsAsync.

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, string)

Reads one retained revision's template.

Inherited from IPageCatalog.ReadRevisionAsync.

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.

Pages.PageChain

One render: the page the visitor asked for, the pages that wrap it, and the pages it includes.

A render is a tree. The page's body and the wrappers around it are one spine, and every layer may embed, which is a child render with a spine of its own. The host walks it by making the calls, and the ancestor stack is the path down it: the chain refuses to enter the same page with the same request twice, which is what bounds a page that composes itself.

Every layer is a real render of a real page: its own key, and so its own storage handle, under the request's path and the session's one slot, deadline and body budget.

Creates the chain for one request.

Parameters

environment
What the endpoint needs beyond the renderer.
editor
The page store's writer, when the host has one; every layer that is not a layout is offered it, and a host without one offers no write at all.
loggerFactory
Creates the logger every layer writes through.
request
The request snapshot, shared by every layer.
user
The signed-in account, or null.
session
The visitor's session, resolved once by the endpoint.
isHead
Whether the request is a HEAD, which renders but never writes state.
bodyBudget
The allowance the whole render shares.
bodySink
Where a flushing content layer writes its response.
fetchBudget
The fetch allowance the whole render shares.
readBudget
The template allowance the whole render shares.
assets
The live assets every layer's links may be versioned against.
shellLinks
The shell's links as values, built once for this request so every layer's catalog answers the same and the sign-in link carries the visitor's way back.
loginRedirect
Where a guard sends an anonymous visitor.
antiforgeryField
Mints the antiforgery pair once per request, so every layer's form is verifiable against the same token.
render
The render session every layer runs under. It is opened before the content layer is built, so an embed holds the session it belongs to.
aborted
The request's cancellation token, shared by every layer.

PropertyDefaultLayout

The page a bare Wrap names, or null.

MethodIsReserved(PagePath key)

Whether a key belongs to the shell rather than to the page store.

Parameters

key
The canonical key.

MethodCreateLayer(PagePath key, Pages.PageLayerRole role, PageRequest request, Pages.BodyBudget budget, IReadOnlyList<Pages.PageRenderIdentity> path, int depth, PageCapture content)

Builds one layer of the render.

Parameters

key
The layer's canonical key.
role
What the layer is, which decides what it may do.
request
The request the layer runs against; its path is still the visitor's.
budget
The allowance this layer's writes are charged to.
path
The chain down to and including this layer.
depth
How many embeds sit above this layer.
content
The layer inside this one, when this layer wraps another.

MethodWrapAsync(PagePath path, Pages.PageLayer content, PageResponse response)

Wraps the content in the pages it declared, outermost last.

Parameters

path
The page the visitor asked for.
content
The content layer, after it ran.
response
What the content asked the response to be.

Returns

The body to write, or the error that says why the chain could not be built.

MethodComposeAsync(PagePath key, PageRequest request, IReadOnlyList<Pages.PageRenderIdentity> path, int depth)

Renders a page inside another one, wrappers and all, and returns what it produced.

Parameters

key
The embedded page's canonical key.
request
The request it runs against.
path
The chain that asked for it, which the recursion check reads.
depth
How many embeds already sit above the layer that asked.

Exceptions

InvalidOperationException
The page repeats in the chain, or a cap was reached.
The page, or a page wrapping it, cannot be served.
OperationCanceledException
The render's deadline fired while it ran.

Pages.PageChainFailureException

A chain that could not be built, worded for the reader of the page that asked for it.
The endpoint turns this into the error document for the page the visitor asked for; an embed turns it into a UserFacingException the page may catch, because an embedded page's failure never reached the caller's body.

MethodPageChainFailureException(int statusCode, Errors.ErrorMessage error)

A chain that could not be built, worded for the reader of the page that asked for it.
The endpoint turns this into the error document for the page the visitor asked for; an embed turns it into a UserFacingException the page may catch, because an embedded page's failure never reached the caller's body.

Parameters

statusCode
The status the top-level page would answer with.
error
What to tell the reader.

PropertyStatusCode

The status the top-level page answers with.

PropertyError

What to tell the reader.

Pages.PageChainResult

What a page and its layouts came to.
Closed: the chain either serves a document or fails; there is no third outcome.

Pages.PageChainResult.Failed

The chain could not be built, so there is a failure to report instead of a document.

MethodFailed(int StatusCode, Errors.ErrorMessage Error)

The chain could not be built, so there is a failure to report instead of a document.

Parameters

StatusCode
The status to send.
Error
What to tell the reader.

PropertyStatusCode

The status to send.

PropertyError

What to tell the reader.

Pages.PageChainResult.Served

The chain produced a document.

MethodServed(PageResponse Response, string Body)

The chain produced a document.

Parameters

Response
The response the content owns, with every layer's script permission.
Body
The outermost layer's body.

PropertyResponse

The response the content owns, with every layer's script permission.

PropertyBody

The outermost layer's body.

Pages.PageCommitState

Whether one layer of a render has committed its response.
Shared by the context that flushes and the capabilities that would need to set a header after it. The flag is read by the page's own task and by the abandoning thread, so it is volatile rather than merely lock-protected.

PropertyCommitted

Whether the first flush has happened.

Pages.PageCompositionScope

One layer's IPageComposition: what it may include, and what may wrap it.
A thin adapter over the chain: the chain owns the render, the budgets and the ancestor stack, and this holds the facts that make the calls the caller's — its request, its place in the chain and the response an embed writes into.

MethodPageCompositionScope(Pages.PageChain, Pages.PageCompositionState, PageRequest, IReadOnlyList<Pages.PageRenderIdentity>, int, PagePath, Func<Pages.SimpleResponse>)

One layer's IPageComposition: what it may include, and what may wrap it.
A thin adapter over the chain: the chain owns the render, the budgets and the ancestor stack, and this holds the facts that make the calls the caller's — its request, its place in the chain and the response an embed writes into.

MethodEmbedAsync(string, PageRequest)

Renders another stored page where the call is, wrappers and all.

Inherited from IPageComposition.EmbedAsync.

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, PageRequest)

Renders another stored page, and returns its body instead of writing it.

Inherited from IPageComposition.CaptureAsync.

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, PageRequest)

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

Inherited from IPageComposition.Wrap.

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.

Inherited from IPageComposition.Wrap.

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.

Pages.PageCompositionState

The wrappers one layer declared, innermost first.
A declaration, not a handover: the host runs the chain after the page returns, so an early return; from a guard is still wrapped. Each call adds a layer outside the last.

PropertyWraps

The wrappers, in the order the page declared them.

PropertyIsEmpty

Whether the page declared no wrapper, so it is served exactly as it wrote itself.

MethodWrap(PagePath key, PageRequest request, bool isDefault)

Records one wrapper outside every layer already declared.

Parameters

key
The wrapper's canonical key.
request
The request the wrapper runs against.
isDefault
Whether this is the site's layout rather than a named page.

Pages.PageContentHashRepair

Fills in the content hash of every head written before the column existed.

The anchor a seed write records cannot be recovered, and is not invented: a repaired page stays unknown until something establishes where it came from. The content hash can be recovered exactly, because the head's revision holds the source it was computed from. That is enough to tell a legacy page that matches its shipped seed (adoptable) from one that does not (unknown).

It runs once after the migration and before the start seeder, in one transaction, and is idempotent: a row that already has a hash is never read. It is deliberately not inside the EF migration — SQLite has no SHA-256 and migrations get no context, so the alternative would be a frozen second copy of the algorithm.

MethodRunAsync(Storage.StorageDbContext database, CancellationToken cancellationToken)

Repairs every head whose content hash is missing.

Parameters

database
The store to repair.
cancellationToken
Cancels the repair.

Returns

How many heads it repaired.

Pages.PageContentTypesConfiguration

Reads Pages:ContentTypes into the pure map a page's response is shaped from.

The section is ordinary configuration beside the other page options, so a host changes the map in its own appsettings.Production.json and restarts rather than rebuilding the image. It is read once; nothing in the shell observes changes while the process runs.

A row is either the shorter spelling — a media type string, which by definition has script policy none — or an object with ContentType and ScriptPolicy. The policy belongs to the extension, not to the final response type. The fallback and at least one extension are required.

MethodFromConfiguration(IConfiguration configuration, ILogger logger)

Reads the section and reports the map once.

Parameters

configuration
The application configuration.
logger
Where the map is reported once.

Exceptions

A row is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:ContentTypes into the caller's report.

Parameters

reader
A reader opened on Pages:ContentTypes, which the caller completes.

MethodLog(ILogger logger, PageContentTypes contentTypes)

Reports the map the site will serve.

Parameters

logger
Where the map is reported once.
contentTypes
The map that was read.

Pages.PageCredential

An operator-configured credential a page names but never reads.

Only HeaderValue reads the secret, and only Pages.OutboundFetcher calls it as it attaches the header. ToString deliberately leaves the value out, so an accidental log line cannot carry it.

The credential is bound to one page or to a page and everything under it, so pages that share an API name one entry rather than duplicating the secret for each of them.

It is a class rather than a record because the generated record ToString would print every property, the value included.

MethodPageCredential(string, string, string, string, string, PagePath, bool)

An operator-configured credential a page names but never reads.

Only HeaderValue reads the secret, and only Pages.OutboundFetcher calls it as it attaches the header. ToString deliberately leaves the value out, so an accidental log line cannot carry it.

The credential is bound to one page or to a page and everything under it, so pages that share an API name one entry rather than duplicating the secret for each of them.

It is a class rather than a record because the generated record ToString would print every property, the value included.

PropertyName

The name a page uses to ask for this credential.

PropertyHost

The only host the header may be sent to, in Uri.IdnHost form.

PropertyHeader

The request header that carries the value.

PropertyPage

The page this credential is bound to, or the root of the subtree it is bound to.

PropertyIncludesDescendants

Whether the pages under Page may name this credential too.

PropertyScope

The pages that may name this credential, as a phrase safe to log.

PropertyHeaderValue

The header value: the scheme and one space, then the secret, or the secret alone.

MethodAppliesTo(Uri uri)

Whether this credential may be attached to a request for uri.

Parameters

uri
The request or redirect target.

Returns

true on the credential's host over HTTPS, or over plaintext when that host is loopback.

MethodIsBoundTo(string key)

Whether this credential belongs to the page with key.

Parameters

key
The canonical page key.

Returns

true for the page named in the credential's configuration, and for any page below it when the entry's Page ended in /*.

MethodToString()

Names the credential and its scope, never its value.

Returns

A line safe to log.

Pages.PageDiagnostics

Turns the compiler's diagnostics into the values a page may name.
Every author-facing message is "{code}: {text}" in the one form every producer writes — Roslyn's "CS1002: ; expected" and the host's own "PAGE001: ..." alike — so the code is the prefix of the message rather than a field of its own (`pages-a-page-may-save-itself`). One mapping serves a self-save and the editor.

MethodToSdk(IEnumerable<PageDiagnostic> diagnostics)

Maps the compiler's answer, ordered by template position.

Parameters

diagnostics
The compiler's diagnostics.

MethodToSdk(PageDiagnostic diagnostic)

Maps one of the compiler's diagnostics.

Parameters

diagnostic
The compiler's diagnostic.

Pages.PageEditorOptions

Where the editor is served, and the key every link to it is built from.
The capability is offered to every page now, so this key decides nothing about authority: it says where the editor lives, which is what ctx.EditorPath, the shell's remedy links and every ?edit= URL read. A key no request could reach is still refused at startup rather than left to become a site with no editor.

PropertyKey

The page key where the editor is served.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Editor.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Editor into the caller's report.

Parameters

reader
A reader opened on Pages:Editor, which the caller completes.

Pages.PageEndpoint

The endpoint that serves pages, and the only one that does so.

MethodPageEndpoint()

The endpoint that serves pages, and the only one that does so.

Pages.PageEnvironment

What the page endpoint needs beyond the renderer, gathered in one place.
Every member is a singleton, so the record is one too; it exists so the endpoint's signature stays readable as the page contract grows a capability.

MethodPageEnvironment(Pages.ReservedPaths Reserved, Pages.PageEditorOptions Editor, Pages.PageLayoutOptions Layout, Pages.RenderOptions Render, PageContentTypes ContentTypes, Pages.PageStorageOptions Storage, Pages.PageFetchOptions Fetch, Pages.PageReadOptions Read, Pages.IPageStateStore StateStore, Pages.IPageReadStore ReadStore, Pages.PageSeeds Seeds, Editor.PageSaver Saver, Pages.IPageFetcher Fetcher, Pages.PageMetrics Metrics, IAntiforgery Antiforgery, MarkdownRenderer Markdown, DiffRenderer Diff, Pages.PageSessionOptions Sessions, Pages.IPageSessionStore SessionStore, Authentication.PageSessionCookieOptions SessionCookie, Work.PageJobs Jobs)

What the page endpoint needs beyond the renderer, gathered in one place.
Every member is a singleton, so the record is one too; it exists so the endpoint's signature stays readable as the page contract grows a capability.

Parameters

Reserved
The keys the site's own routes answer for.
Editor
The one key offered the editor capability.
Layout
The page every HTML page with code is wrapped in unless it says otherwise.
Render
The render budget and body cap.
ContentTypes
The media type and script policy each page key's extension names.
Storage
The storage caps.
Fetch
The outbound fetch caps.
Read
The caps on a page's read of the page store.
StateStore
Where a page's state is read and written.
ReadStore
Where a page's catalog reads the page store.
Seeds
The pack this release ships, read once.
Saver
Where a page's save, and the editor's, compiles and stores a revision.
Fetcher
Where a page's outbound request goes.
Metrics
Where the endpoint's own refusals are recorded.
Antiforgery
Validates a page's post and mints the field a form carries.
Markdown
The renderer every page layer offers as IMarkdownRenderer.
Diff
The renderer every page layer offers as IDiffRenderer.
Sessions
The bounds on one visitor's session.
SessionStore
Where a visitor's session is read and written.
SessionCookie
The cookie that names the visitor's session.
Jobs
Where a page's jobs are started and read, or null when this host offers none. A host without one simply does not offer the capability, which is what a page is already prepared for.

PropertyReserved

The keys the site's own routes answer for.

PropertyEditor

The one key offered the editor capability.

PropertyLayout

The page every HTML page with code is wrapped in unless it says otherwise.

PropertyRender

The render budget and body cap.

PropertyContentTypes

The media type and script policy each page key's extension names.

PropertyStorage

The storage caps.

PropertyFetch

The outbound fetch caps.

PropertyRead

The caps on a page's read of the page store.

PropertyStateStore

Where a page's state is read and written.

PropertyReadStore

Where a page's catalog reads the page store.

PropertySeeds

The pack this release ships, read once.

PropertySaver

Where a page's save, and the editor's, compiles and stores a revision.

PropertyFetcher

Where a page's outbound request goes.

PropertyMetrics

Where the endpoint's own refusals are recorded.

PropertyAntiforgery

Validates a page's post and mints the field a form carries.

PropertyMarkdown

The renderer every page layer offers as IMarkdownRenderer.

PropertyDiff

The renderer every page layer offers as IDiffRenderer.

PropertySessions

The bounds on one visitor's session.

PropertySessionStore

Where a visitor's session is read and written.

PropertySessionCookie

The cookie that names the visitor's session.

PropertyJobs

Where a page's jobs are started and read, or null when this host offers none. A host without one simply does not offer the capability, which is what a page is already prepared for.

Pages.PageFetchHeaders

The header names a page may send and see.

Both lists are allow-lists rather than filters. Framing headers, Host, Cookie and Set-Cookie are refused outright, so nothing ambient is forwarded and nothing ambient comes back; a page that means to send a credential does it through Authorization on purpose.

User-Agent is accepted so a page that already sets one is not refused, but Pages.OutboundFetcher replaces it with Pages.OutboundUserAgent's value: the identity a remote service sees is the site's and the origin's, never a page's claim.

MethodIsRequestAllowed(string name)

Whether a page may send a header with this name.

Parameters

name
The header name.

Returns

true for a listed name or an X- name.

MethodIsResponseAllowed(string name)

Whether a response header is returned to the page.

Parameters

name
The header name.

Returns

true for a listed name or an X- name.

Pages.PageFetchOptions

Bounds the host's outbound HTTP, for pages and for the assistant's fetch tool.

There is no host allow-list: any absolute http or https URL is reachable, and the guards here are about shape and size rather than destination (`pages-outbound-fetch`). The container's egress is not otherwise restricted, so this is a footgun guard, not a sandbox.

The timeout is below the default render budget on purpose, so a slow API becomes a value the page can render instead of a 504.

FieldMaximumCredentialNameLength

The longest credential name Pages:Fetch:Credentials accepts.

PropertyTimeoutSeconds

How long one fetch may take.
May be a fraction of a second, down to MinimumTimeoutSeconds.

PropertyMaxResponseBytes

The most decompressed bytes one response may return.

PropertyStreamSilenceSeconds

How long a streamed response may go without producing a line.

PropertyStreamMaxSeconds

The longest a streamed response may stay open.

PropertyMaxStreamBytes

The most bytes a streamed response may return.

PropertyMaxRequestsPerRender

The most requests one render may make.

PropertyMaxRedirects

The most redirects one fetch may follow; zero disables following.

PropertyCredentials

The operator-configured credentials a page may name, by name.

PropertyTimeout

The per-fetch budget as a time span.

PropertyStreamSilence

The stream's silence budget as a time span.

PropertyStreamMax

The stream's absolute budget as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Fetch.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Fetch into the caller's report.

Parameters

reader
A reader opened on Pages:Fetch, which the caller completes.

Pages.PageFetcher

Makes a page's outbound HTTP request, bounded and metered.
The request itself belongs to Pages.OutboundFetcher; this is the page-shaped edge that names the page in the metric and holds the page's key to the same value contract as the SDK. A page may fetch any http or https host (`pages-outbound-fetch`). A named credential is resolved and bound to this page here, before Pages.OutboundFetcher opens a socket.

MethodPageFetcher(Pages.OutboundFetcher, Pages.PageFetchOptions, Pages.PageMetrics, ILogger<Pages.PageFetcher>)

Makes a page's outbound HTTP request, bounded and metered.
The request itself belongs to Pages.OutboundFetcher; this is the page-shaped edge that names the page in the metric and holds the page's key to the same value contract as the SDK. A page may fetch any http or https host (`pages-outbound-fetch`). A named credential is resolved and bound to this page here, before Pages.OutboundFetcher opens a socket.

MethodFetchAsync(HttpFetchRequest, string, CancellationToken, CancellationToken)

Makes one bounded outbound request.

Inherited from Pages.IPageFetcher.FetchAsync.

The two tokens travel separately rather than linked, because a refusal has to say which one fired: the visitor leaving is Aborted, and the render running out of budget is Timeout.

Parameters

request
The page's request.
pagePath
The page's key, for the metric and log tags.
aborted
Cancelled when the visitor went away.
deadline
Cancelled when the render's budget ran out.

Returns

The response; a failure is reported in the value, not thrown.

MethodStreamAsync(HttpFetchRequest, string, CancellationToken, CancellationToken)

Opens one bounded outbound response stream.

Inherited from Pages.IPageFetcher.StreamAsync.

Parameters

request
The page's request.
pagePath
The page's key, for the metric and log tags.
aborted
Cancelled when the visitor went away.
deadline
Cancelled when the render or stream budget ran out.

Returns

The stream; failures are reported through its values.

Pages.PageHead

The storage row that points a page key at its current revision.

PropertySeedHash

The content hash of the seed this page's content is anchored to, or null when unknown.

PropertyContentHash

The content hash of the head's stored source.

Pages.PageHeadSummary

One row of the page list: the key, whether the page is deleted, and its two hashes.

MethodPageHeadSummary(PagePath Path, bool IsDeleted, string SeedHash, string ContentHash)

One row of the page list: the key, whether the page is deleted, and its two hashes.

Parameters

Path
The canonical key.
IsDeleted
Whether the row is a tombstone.
SeedHash
The seed the page's content is anchored to, or null when unknown.
ContentHash
The content hash of the head's stored source.

PropertyPath

The canonical key.

PropertyIsDeleted

Whether the row is a tombstone.

PropertySeedHash

The seed the page's content is anchored to, or null when unknown.

PropertyContentHash

The content hash of the head's stored source.

Pages.PageHealth

Counts the page renders that outran their budget and were abandoned.
A render that never returns cannot be reclaimed, but it can be noticed: once Limit renders are outstanding the site stops reporting healthy and the supervisor restarts the container. That is the only kill this design has, so the count is what makes it happen. A page may still finish after it was given up on, which is why the count can go down again.

MethodPageHealth(int)

Counts the page renders that outran their budget and were abandoned.
A render that never returns cannot be reclaimed, but it can be noticed: once Limit renders are outstanding the site stops reporting healthy and the supervisor restarts the container. That is the only kill this design has, so the count is what makes it happen. A page may still finish after it was given up on, which is why the count can go down again.

PropertyLimit

Abandoned renders allowed before the site reports unhealthy.

PropertyAbandoned

Renders that have been given up on and have not finished since.

MethodRegister()

Records a render that was abandoned.

MethodRelease()

Records that an abandoned render eventually finished.

Pages.PageHttpFetch

The host's IHttpFetch, bound to one layer and the render's budget.

Every refusal is a value rather than an exception, so a page can fall back without a try. Only abandonment throws: the render has already been answered, so there is no page left to read a value.

The deadline arrives after construction, from the renderer, so the capability reads it per call rather than capturing a token that did not exist yet.

MethodPageHttpFetch(PagePath, bool, CancellationToken, Pages.IPageFetcher, Pages.PageFetchOptions, Pages.RenderFetchBudget, Pages.PageMetrics, ILogger)

The host's IHttpFetch, bound to one layer and the render's budget.

Every refusal is a value rather than an exception, so a page can fall back without a try. Only abandonment throws: the render has already been answered, so there is no page left to read a value.

The deadline arrives after construction, from the renderer, so the capability reads it per call rather than capturing a token that did not exist yet.

MethodSendAsync(HttpFetchRequest)

Makes one bounded outbound HTTP request.

Inherited from IHttpFetch.SendAsync.

Parameters

request
The request to make.

Returns

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

MethodStreamAsync(HttpFetchRequest)

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

Inherited from IHttpFetch.StreamAsync.

Parameters

request
The request to make.

Returns

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

MethodAttachLifetime(Pages.RenderLifetime)

Attaches the render lifetime and its asynchronous cleanup boundary.

Inherited from Pages.IRenderLifetimeAware.AttachLifetime.

Parameters

lifetime
The render lifetime that owns this capability.

Pages.PageImage

The image compiled from a page's template, stored beside it.

MethodPageImage(string TemplateHash, string RuntimeId, byte[] Bytes, byte[] Symbols, IReadOnlyList<PageDiagnostic> Diagnostics, PageKind? Kind, string Libraries)

The image compiled from a page's template, stored beside it.

Parameters

TemplateHash
The fingerprint of the template the image was built from.
RuntimeId
The build that produced the image.
Bytes
The emitted assembly, or null when compilation failed or there was nothing to compile.
Symbols
The emitted portable PDB, or null when compilation failed.
Diagnostics
The compiler's author-facing diagnostics, errors and warnings, in template space; empty when the template compiled cleanly.
Kind
What the template is for, or null when the stored row has never been judged. A record built by generation always knows; a stored image from before the verdict existed keeps the null.
Libraries
The fingerprint of the libraries the image was compiled against, or null when it named none. A page whose closure has moved is compiled again before it runs.

PropertyTemplateHash

The fingerprint of the template the image was built from.

PropertyRuntimeId

The build that produced the image.

PropertyBytes

The emitted assembly, or null when compilation failed or there was nothing to compile.

PropertySymbols

The emitted portable PDB, or null when compilation failed.

PropertyDiagnostics

The compiler's author-facing diagnostics, errors and warnings, in template space; empty when the template compiled cleanly.

PropertyKind

What the template is for, or null when the stored row has never been judged. A record built by generation always knows; a stored image from before the verdict existed keeps the null.

PropertyLibraries

The fingerprint of the libraries the image was compiled against, or null when it named none. A page whose closure has moved is compiled again before it runs.

MethodIsCurrent(string templateHash, string runtimeId, string libraries)

Whether the stored image still matches the template, the build and the libraries.

Parameters

templateHash
The fingerprint of the template as it is now.
runtimeId
The build that is running now.
libraries
The fingerprint of the live libraries, or null when the page named none.

Pages.PageImageBuilder

Turns a page template into the image stored beside it.

This is the Web half of compilation: generate a Compilation.GeneratedSource, wait for a compile slot, bound the compile, and turn the result into a Pages.PageImage. It never touches storage, so a save and a lazy compile share it without either owning the other.

Records page.compile.duration and page.image.size.

MethodPageImageBuilder(IPageCompiler, Pages.PageBudget, Pages.PageMetrics, ILogger<Pages.PageImageBuilder>)

Turns a page template into the image stored beside it.

This is the Web half of compilation: generate a Compilation.GeneratedSource, wait for a compile slot, bound the compile, and turn the result into a Pages.PageImage. It never touches storage, so a save and a lazy compile share it without either owning the other.

Records page.compile.duration and page.image.size.

Pages.PageImageState

What a page's stored image amounts to, as the editor and the assistant describe it.
An image with an assembly carries warnings only, because emit either succeeds or reports an error, so CompiledWithWarnings is the worst a stored and runnable page can be. The state is a value rather than a string so a view cannot invent another way of saying the same thing; Describe is the only spelling of the words.

A library is checked rather than emitted, so it never has an assembly and its diagnostics are its only signal. The listing can therefore say that a library's check reported something, but not whether it was a warning or an error; the editor shows the diagnostics themselves. A worker is emitted like a page, so its image says which of the two it reached.

FieldStoredAsSource

The template has no code, so it is stored and served as source.

FieldNotCompiled

No image has been built for the template yet.

FieldStale

The image was built by another build, so its diagnostics predate the running one.

FieldCompileFailed

An image record exists and carries no assembly.

FieldCompiledWithWarnings

An assembly with diagnostics, which are warnings.

FieldCompiled

An assembly with nothing to report.

FieldLibrary

A library whose check is current and reported nothing.

FieldLibraryWithIssues

A library whose check reported a warning or an error.

FieldWorker

A worker whose image is current and carries nothing to report.

FieldWorkerWithWarnings

A worker whose image compiled with warnings.

Pages.PageImageStatus

Decides an image's state, and the words and classes it is shown with.
The strings reach the author in the page list, the editor's history and the assistant's tool results, so they are written once here rather than in each view that needs them.

MethodDescribe(string runtimeId, bool hasImage, bool hasDiagnostics, string currentRuntimeId, PageKind? kind)

Describes a stored image's state.
A library never carries an assembly, so hasImage plays no part in its state: the check is the record, and its diagnostics are what it reported.

Parameters

runtimeId
The build that made the image, or null when there is no image record.
hasImage
Whether the record carries an emitted assembly.
hasDiagnostics
Whether compiling it reported anything.
currentRuntimeId
The build that is running now, or null to leave staleness unjudged: a retained revision from an earlier build is history rather than stale, and only the listing and the assistant ask.
kind
What the template is for, or null when it has never been judged.

Returns

The state the words are chosen from.

MethodDescribe(Pages.PageImageState state)

The words a state is shown with.

Parameters

state
The state to describe.

Returns

The words, which read correctly with no stylesheet at all.

MethodClass(Pages.PageImageState state)

The class a view puts on the element that carries the words.

Parameters

state
The state to name.

Returns

One class per state, so a stylesheet can mark the ones that want attention.

Pages.PageJobEnvironment

What a job needs from the shell, gathered in one place.
It is the job's half of Pages.PageEnvironment: the same stores and caps a render uses, minus everything about a response, a visitor's session or a layout, because a job has none of those.

MethodPageJobEnvironment(Pages.PageJobOptions Jobs, Work.IWorkerStore Store, Pages.IPageStateStore State, Pages.PageStorageOptions Storage, Pages.IPageFetcher Fetcher, Pages.PageFetchOptions Fetch, Pages.IPageReadStore Seeds, Pages.PageSeeds ReadStore, Pages.PageReadOptions Read, Pages.ReservedPaths Reserved, PageContentTypes ContentTypes, Pages.PageImageBuilder Images, Pages.PageLibraries Libraries, IPageCompiler Compiler, Pages.PageMetrics Metrics)

What a job needs from the shell, gathered in one place.
It is the job's half of Pages.PageEnvironment: the same stores and caps a render uses, minus everything about a response, a visitor's session or a layout, because a job has none of those.

Parameters

Jobs
The job bounds.
Store
Where a job reads its worker and stores a rebuilt image.
State
Where the starting page's state is read and written.
Storage
The caps on that state.
Fetcher
Where a worker's outbound request goes.
Fetch
The outbound fetch caps.
Seeds
The pack this release ships, so a worker's catalog can describe it.
ReadStore
Where a worker's catalog reads the page store.
Read
The caps on that read.
Reserved
The keys the site's own routes answer for.
ContentTypes
The media type each page key's extension names.
Images
Builds a worker's image when its library has moved.
Libraries
The live libraries a worker may be compiled with.
Compiler
Loads the worker's image and finds its entry point.
Metrics
Where a worker's own fetches are recorded.

PropertyJobs

The job bounds.

PropertyStore

Where a job reads its worker and stores a rebuilt image.

PropertyState

Where the starting page's state is read and written.

PropertyStorage

The caps on that state.

PropertyFetcher

Where a worker's outbound request goes.

PropertyFetch

The outbound fetch caps.

PropertyReadStore

Where a worker's catalog reads the page store.

PropertySeeds

The pack this release ships, so a worker's catalog can describe it.

PropertyRead

The caps on that read.

PropertyReserved

The keys the site's own routes answer for.

PropertyContentTypes

The media type each page key's extension names.

PropertyImages

Builds a worker's image when its library has moved.

PropertyLibraries

The live libraries a worker may be compiled with.

PropertyCompiler

Loads the worker's image and finds its entry point.

PropertyMetrics

Where a worker's own fetches are recorded.

Pages.PageJobOptions

Bounds a job that runs a stored worker after the request that started it has gone.

A job answers nobody, so the render budget is the wrong question. It has its own lifetime — a silence clock that catches a stall, re-armed by everything the worker does, and a ceiling that ends work which never stops — its own slots, and its own bounds on the messages it takes and the events it publishes. Every value comes from Pages:Jobs.

The shipped ceiling is nine hours, because a worker that runs for a working day is the point; the silence clock is what notices one that has wedged.

PropertyQueueCapacity

Jobs waiting for a runner.

PropertyMaxConcurrent

Jobs allowed to run at once.

PropertySilenceSeconds

How long a job may go without publishing or receiving before it is cut.

PropertyMaxDurationSeconds

The longest a job may run, measured from its start.

PropertyMaxEvents

Events one job's journal keeps before it drops the oldest.

PropertyMaxEventBytes

The most bytes one job's journal holds before it drops the oldest.

PropertyRetentionMinutes

How long a finished job's journal is kept before the record goes.

PropertyMaxWaitSeconds

The longest a viewer's read may wait for an event that has not arrived.

PropertyMaxMessageBytes

The most bytes one message to or from a worker may carry.

PropertyMaxPendingMessages

Messages a running job may hold before another is refused.

PropertySilence

The silence clock as a time span.

PropertyMaxDuration

The ceiling as a time span.

PropertyRetention

The retention as a time span.

PropertyMaxWait

The wait cap as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Jobs.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Jobs into the caller's report.

Parameters

reader
A reader opened on Pages:Jobs, which the caller completes.

Pages.PageJobsScope

One layer's IPageJobs, bound to that render's visitor.

It is offered to every page layer and never to a layout: a layout that started work would start it once per page it wraps, and the page that can read the events is the one that asked for the job. Nobody is offered it by IContext — a page that never wants a job never meets one.

A HEAD is offered the reads and not the writes, because a HEAD runs the page to produce its representation and starting work is a side effect the visitor never asked for. The refusal is a value rather than an exception, so a page can branch on it.

MethodPageJobsScope(PagePath, bool, PageUser, Work.PageJobs, Pages.PageJobOptions)

One layer's IPageJobs, bound to that render's visitor.

It is offered to every page layer and never to a layout: a layout that started work would start it once per page it wraps, and the page that can read the events is the one that asked for the job. Nobody is offered it by IContext — a page that never wants a job never meets one.

A HEAD is offered the reads and not the writes, because a HEAD runs the page to produce its representation and starting work is a side effect the visitor never asked for. The refusal is a value rather than an exception, so a page can branch on it.

MethodStartAsync(string, string)

Starts one run of the worker stored at workerKey.

Inherited from IPageJobs.StartAsync.

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, string)

Sends a message to a running job.

Inherited from IPageJobs.SendAsync.

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)

Reads one job, if this visitor owns it.

Inherited from IPageJobs.GetAsync.

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.

Inherited from IPageJobs.ListAsync.

Returns

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

MethodReadEventsAsync(string, long, double?)

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

Inherited from IPageJobs.ReadEventsAsync.

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)

Asks a job to stop.

Inherited from IPageJobs.CancelAsync.

Parameters

jobId
The id a start or a listing answered with.

Returns

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

Pages.PageLayer

One layer of a render: what the page runs through, its slots, and what it declared.

MethodPageLayer(Pages.SimpleContext Context, Pages.PageLayoutState Layout, Pages.PageCompositionState Composition, IReadOnlyList<Pages.PageRenderIdentity> Path, int Depth)

One layer of a render: what the page runs through, its slots, and what it declared.

Parameters

Context
The context the page runs against.
Layout
The layer's own slots.
Composition
The wrappers the page declared, innermost first.
Path
The chain down to and including this layer, which is what an embed or a wrap is checked against.
Depth
How many embeds sit above this layer, which is the depth cap's measure.

PropertyContext

The context the page runs against.

PropertyLayout

The layer's own slots.

PropertyComposition

The wrappers the page declared, innermost first.

PropertyPath

The chain down to and including this layer, which is what an embed or a wrap is checked against.

PropertyDepth

How many embeds sit above this layer, which is the depth cap's measure.

Pages.PageLayerRole

What one layer of a render is, which decides what it may do.
One value rather than a flag beside a special case: the response gates, the stream refusals, the offers of the write, the jobs and a writable session, and the layout slot all read it.

FieldContent

The page the visitor asked for: it owns the response and may be wrapped.

FieldLayout

A page wrapping another: markup, with no response of its own.

FieldEmbedded

A page rendered inside another: a content page that owns no response.

Pages.PageLayoutOptions

The page every HTML page with code is wrapped in unless it says otherwise.
Read once at startup from Pages:Layout. The value must be present; an explicit blank switches wrapping off, so an installation that wants no wrapping at all has a configuration answer rather than a code change. The key is canonicalised so a layout is named the same way a request would name it.

PropertyDefault

The layout every page is wrapped in, or null when there is none.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Layout.

Parameters

configuration
The application configuration.

Exceptions

The value is missing.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Layout into the caller's report.

Parameters

reader
A reader opened on Pages:Layout, which the caller completes.

Pages.PageLayoutState

One layer's IPageLayout: its own slots, and the layer inside it.
The host no longer composes the layer inside into these slots: Content is handed over and the wrapper folds what it wants. That is what makes a wrapper and an embed the same relation from opposite ends.

PropertyContent

The layer inside this one, when this is a wrapper; null otherwise.

Inherited from IPageLayout.Content.

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.

Inherited from IPageLayout.Title.

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.

Inherited from IPageLayout.Head.

PropertyStylesheets

A sheet this layer asked for twice is linked once.

MethodAddHead(string)

Adds raw markup to the document's head.

Inherited from IPageLayout.AddHead.

Parameters

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

MethodAddStylesheet(string)

Links one stylesheet from the document.

Inherited from IPageLayout.AddStylesheet.

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.

Pages.PageLibraries

The live libraries a page may name, read through the page read seam.
A compiler needs the libraries a page could reach, and a render needs to know whether the ones it was compiled against have moved. Both answers come from the same listing, so the sources are only read when something is actually going to compile.

MethodPageLibraries(Pages.IPageReadStore)

The live libraries a page may name, read through the page read seam.
A compiler needs the libraries a page could reach, and a render needs to know whether the ones it was compiled against have moved. Both answers come from the same listing, so the sources are only read when something is actually going to compile.

MethodHeadsAsync(CancellationToken)

The identity of every live library, ordered by key.

MethodLiveAsync(CancellationToken)

Every live library and its source, ordered by key.

Pages.PageLibrary

One live library, as a compile reads it.

MethodPageLibrary(PagePath Key, string Hash, string Template)

One live library, as a compile reads it.

Parameters

Key
The library's canonical key.
Hash
The head revision's hash, which a dependent's fingerprint records.
Template
The library's source.

PropertyKey

The library's canonical key.

PropertyHash

The head revision's hash, which a dependent's fingerprint records.

PropertyTemplate

The library's source.

Pages.PageLibraryFingerprint

The fingerprint a page's image records of the libraries it was compiled against.

MethodOf(IEnumerable<ValueTuple<string, string>> libraries)

Fingerprints the closure: one key@hash per library, in ordinal key order.

Parameters

libraries
The keys and the revision hashes they were compiled from.

Returns

The fingerprint, or an empty string when the page named no library. It is stored beside the image and compared with the heads, so a moved library makes exactly its dependents stale.

Pages.PageLibraryHead

One live library's identity, which is all a staleness check needs.

MethodPageLibraryHead(PagePath Key, string Hash)

One live library's identity, which is all a staleness check needs.

Parameters

Key
The library's canonical key.
Hash
The head revision's hash.

PropertyKey

The library's canonical key.

PropertyHash

The head revision's hash.

Pages.PageListing

One row of the page list: the key, whether it is deleted, and the state of its image.

MethodPageListing(PagePath Path, bool IsDeleted, Pages.PageImageState State)

One row of the page list: the key, whether it is deleted, and the state of its image.

Parameters

Path
The canonical key the page is stored under.
IsDeleted
Whether the page is a tombstone, retaining its history.
State
What the page's current revision compiled to, judged against the running build.

PropertyPath

The canonical key the page is stored under.

PropertyIsDeleted

Whether the page is a tombstone, retaining its history.

PropertyState

What the page's current revision compiled to, judged against the running build.

Pages.PageMetrics

The meter and instruments that describe compiling and rendering pages.
Recording is nearly free until something listens, so the instruments are always on. Instrument names and tag values are a contract for dashboards: change them deliberately.

FieldMeterName

The meter every instrument belongs to.

PropertyInstruments

Every instrument this meter registers, in the order the page lists them.
The catalogue maps each of these to exactly one panel, and PageMetricsTests listens to the meter to prove this list and the registrations below agree. A name renamed in one place and not the other then fails a test rather than emptying a panel.

FieldSecondsBuckets

Buckets for the duration instruments, in seconds.
One scale for every page duration: they are all page-scale work. The top boundary is past the longest deadline these instruments run under — the compile deadline of five seconds, which a save keeps too (`pages-the-execution-budget`, `pages-a-page-may-save-itself`) — so a sample recorded at its deadline lands in a real bucket instead of `+Inf`, and a `504` is exactly the sample the status page is looking for (`metrics-one-panel-per-instrument`).

FieldStreamBuckets

Buckets for page.stream.duration, in seconds.
A stream is measured in the lifetime after its commit, so the scale starts at a second and runs to the longest ceiling the configuration accepts.

FieldImageBuckets

Buckets for page.image.size, in bytes.
Emitting an assembly costs tens of kilobytes, so the scale starts above a kilobyte.

FieldRenderOk

The page was rendered.

FieldRenderCompileError

The page did not compile, so its diagnostics were served instead.

FieldRenderError

An exception escaped the handler.

FieldRenderNotFound

No page is stored under the requested key.

FieldNotFoundPath

The key a request that named no stored page is recorded under.
A miss is unauthenticated and its path is whatever the caller typed, so tagging it verbatim lets a scan mint one time series per URL. The real path is in the access log.

FieldRenderTimeout

The page outran its execution budget and was abandoned.

FieldStreamCeiling

The stream reached its own ceiling.

FieldStreamSilence

The stream went quiet for longer than its silence allows.

FieldStreamCompleted

The stream's page returned normally.

FieldStreamClientLeft

The visitor left, and the stream ended with them.

FieldStreamError

The stream's page faulted after the commit.

FieldAssetServed

An asset was served from source.

FieldAssetNotModified

A versioned asset answered 304 Not Modified.

FieldAssetUnknown

A versioned URL named no retained revision, or one stored under another path.

FieldAssetNonAsset

A versioned URL named a revision that is not a page nothing wraps.

FieldCacheHit

The stored image was used.

FieldCacheMiss

The page had to be compiled to be served.

FieldCacheNone

There was no page to look up.

FieldReasonImport

The page was compiled as part of an import batch.

FieldImportCommitted

Every selected page of the batch was stored.

FieldImportFailed

The batch was refused or its write failed; nothing was stored.

FieldImportAborted

The batch stopped before it wrote anything.

FieldFetchOk

The fetch completed with a 2xx.

FieldFetchHttpError

The remote server answered 4xx or 5xx.

FieldFetchTimeout

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

FieldFetchNetwork

DNS, connect, TLS or protocol failure.

FieldFetchInvalid

The URL, method, body or a header was not acceptable.

FieldFetchLimit

The render had already made as many requests as it may.

FieldFetchRedirectLimit

The redirect limit was reached.

FieldFetchAborted

The visitor left, or the render was abandoned.

FieldStaleLibraryChanged

A library the image was compiled against has moved since.

MethodRecordStream(PagePath path, string outcome, TimeSpan duration)

Records how long a committed stream stayed open and how it ended.

Parameters

path
The page that streamed.
outcome
One of StreamCompleted, StreamSilence, StreamCeiling, StreamClientLeft or StreamError.
duration
The lifetime from the commit to the end.

MethodRecordWait(TimeSpan duration)

Records time spent queueing for a render slot.
Queueing is a property of the site rather than of one page, and the wait is measured before the page is looked up — so this instrument carries no path tag, which is also what keeps a scan from creating a series per URL.

Parameters

duration
How long the request waited.

MethodRecordLayoutFallback(PagePath path)

Records a page served unwrapped because the default layout could not be served.
A fallback is a degradation rather than a fault, so it is counted rather than raised: one deleted page must not take the site down, and this is how an operator notices it anyway.

Parameters

path
The page that was served instead.

MethodRecordRecursiveComposition(PagePath path)

Records a page composed inside itself with a different request.
A recursive component is ordinary — a comment tree, a directory listing — so it is counted rather than warned about: the count says which page does it, and the depth cap is the bound.

Parameters

path
The page that was composed again.

MethodRecordAbandoned(PagePath path)

Records a render that was given up on; it may still be running.

Parameters

path
The page that outran its budget.

MethodRecordAsset(string outcome)

Records one request for an asset.
No path label: the URL is public, so tagging it would let a scan mint a series per address. The access log names the path.

Parameters

outcome
One of AssetServed, AssetNotModified, AssetUnknown or AssetNonAsset.

MethodRecordFetch(PagePath path, string outcome, TimeSpan duration)

Records one outbound fetch.

Parameters

path
The page that made it.
outcome
One of the Fetch* values.
duration
How long it took, including any redirect hops.

MethodRecordImport(string outcome, TimeSpan duration)

Records one import batch.
The batch is one operation, so this carries no per-page timing: it is the archive's work as a whole that an operator watches.

Parameters

outcome
One of ImportCommitted, ImportFailed or ImportAborted.
duration
How long compiling and committing the batch took.

Pages.PageReadHead

One row of a page listing, as the read store answers it.

MethodPageReadHead(string Key, DateTimeOffset SavedAt, string Hash, bool IsDeleted, PageKind? TemplateKind, string RuntimeId, bool HasImage, bool HasDiagnostics, string SeedHash, string ContentHash)

One row of a page listing, as the read store answers it.

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.
TemplateKind
What the head's template is for, or null when it has never been judged.
RuntimeId
The build that compiled the head, or null when it has no image.
HasImage
Whether the head has a stored image.
HasDiagnostics
Whether the head's stored compile has diagnostics.
SeedHash
The seed the page's content is anchored to, or null when unknown.
ContentHash
The content hash of the head's stored source.

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.

PropertyTemplateKind

What the head's template is for, or null when it has never been judged.

PropertyRuntimeId

The build that compiled the head, or null when it has no image.

PropertyHasImage

Whether the head has a stored image.

PropertyHasDiagnostics

Whether the head's stored compile has diagnostics.

PropertySeedHash

The seed the page's content is anchored to, or null when unknown.

PropertyContentHash

The content hash of the head's stored source.

Pages.PageReadOptions

Bounds what one page's read of the store may cost.
Every value comes from Pages:Read. The row cap is the store's limit; the source cap is shared by the whole layout chain, on the same terms as the body and fetch allowances (`pages-one-request-one-chain`).

FieldMaximumRowsPerList

The largest row cap the site will run with.

FieldMinimumSourceCharsPerRender

The smallest source allowance the site will run with.

PropertyMaxRowsPerList

The most rows one listing may return.

PropertyMaxSourceCharsPerRender

How much template text one render may pull in, across every layer.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Read.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Read into the caller's report.

Parameters

reader
A reader opened on Pages:Read, which the caller completes.

Pages.PageReadRevision

One row of a page's history, as the read store answers it.

MethodPageReadRevision(string Hash, DateTimeOffset SavedAt, bool IsCurrent)

One row of a page's history, as the read store answers it.

Parameters

Hash
The revision's hash.
SavedAt
When the revision was saved.
IsCurrent
Whether the live head points at this revision.

PropertyHash

The revision's hash.

PropertySavedAt

When the revision was saved.

PropertyIsCurrent

Whether the live head points at this revision.

Pages.PageReadSource

One template the read store retrieved.

MethodPageReadSource(string Key, string Hash, DateTimeOffset SavedAt, string Template)

One template the read store retrieved.

Parameters

Key
The page's canonical key.
Hash
The revision's hash.
SavedAt
When the revision was saved.
Template
The stored template text.

PropertyKey

The page's canonical key.

PropertyHash

The revision's hash.

PropertySavedAt

When the revision was saved.

PropertyTemplate

The stored template text.

Pages.PageRenderIdentity

One render of one page in a chain: its key and the query it runs against.
The ancestor stack is keyed by this rather than by the key alone, because a page that embeds itself with a different query is a recursive component rather than a cycle. The same key with the same query is the same render, which is the one thing a chain may never contain twice.

MethodPageRenderIdentity(string Key, string Query)

One render of one page in a chain: its key and the query it runs against.
The ancestor stack is keyed by this rather than by the key alone, because a page that embeds itself with a different query is a recursive component rather than a cycle. The same key with the same query is the same render, which is the one thing a chain may never contain twice.

Parameters

Key
The page's canonical key.
Query
The fingerprint of the request's query.

PropertyKey

The page's canonical key.

PropertyQuery

The fingerprint of the request's query.

MethodOf(PagePath key, PageRequest request)

The identity a page has when it runs against a request.

Parameters

key
The page's canonical key.
request
The request it runs against.

Pages.PageRenderer

Runs a stored page, compiling and storing it first when its image cannot be used.

The render budget covers queueing and running, because a visitor waits for both. A page that outruns it cannot be stopped, so the answer is given up on instead: the context is abandoned, the render is counted against the site's health, and the response is a Timeout.

A page wrapped in a layout is several renders of one request, so the slot and the deadline are taken once by a Pages.PageRenderer.RenderSession and every layer renders under it. Otherwise a two-layer page would cost two slots and hold two deadlines.

The handler is asynchronous, so a page that is waiting returns its thread to the pool and unwinds at its next await when the deadline fires. A page that blocks synchronously is unchanged: only abandonment and the container's restart escape it.

A revision the caller has already read can be run without reading the head again, which is how a versioned URL selects one retained revision. A revision with no code is written from its stored source and never compiled, loaded or invoked.

Records page.render.*, page.load.*, page.invoke.* and page.cache.*.

MethodPageRenderer(Pages.IPageStore, IPageCompiler, Pages.PageImageBuilder, Pages.PageLibraries, Pages.PageMetrics, Pages.PageBudget, Pages.PageHealth, ILogger<Pages.PageRenderer>)

Runs a stored page, compiling and storing it first when its image cannot be used.

The render budget covers queueing and running, because a visitor waits for both. A page that outruns it cannot be stopped, so the answer is given up on instead: the context is abandoned, the render is counted against the site's health, and the response is a Timeout.

A page wrapped in a layout is several renders of one request, so the slot and the deadline are taken once by a Pages.PageRenderer.RenderSession and every layer renders under it. Otherwise a two-layer page would cost two slots and hold two deadlines.

The handler is asynchronous, so a page that is waiting returns its thread to the pool and unwinds at its next await when the deadline fires. A page that blocks synchronously is unchanged: only abandonment and the container's restart escape it.

A revision the caller has already read can be run without reading the head again, which is how a versioned URL selects one retained revision. A revision with no code is written from its stored source and never compiled, loaded or invoked.

Records page.render.*, page.load.*, page.invoke.* and page.cache.*.

MethodRenderAsync(PagePath path, Pages.SimpleContext context, CancellationToken cancellationToken)

Runs a page, compiling and storing it first when its stored image cannot be used.

Parameters

path
The canonical key to render.
context
The context the page writes to.
cancellationToken
Cancels the read, any store, and the render itself.

MethodGetPageAsync(PagePath path, CancellationToken cancellationToken)

Reads a page's live head, for an endpoint that must judge it before opening a render.

Parameters

path
The canonical key to read.
cancellationToken
Cancels the read.

MethodGetRevisionByHashAsync(string hash, CancellationToken cancellationToken)

Reads a revision by its hash, for a versioned URL.

Parameters

hash
The revision's stored hash.
cancellationToken
Cancels the read.

MethodRenderAsync(PagePath path, Pages.SimpleContext context, Pages.PageSelection selection, CancellationToken cancellationToken)

Runs a page the caller has already read, rather than reading its head again.

Parameters

path
The canonical key the request named.
context
The context the page writes to.
selection
The revision to run, and whether it came from a versioned URL.
cancellationToken
Cancels the render.

MethodOpenSessionAsync(PagePath path, CancellationToken cancellationToken)

Takes one render slot and one deadline for every layer of a page and its layouts.

Parameters

path
The page the visitor asked for, for the log line and the metric.
cancellationToken
Cancels the wait and every render under the session.

Returns

The session to render the layers under; disposing it releases the slot. A session whose slot wait outlived the budget renders nothing and answers Timeout.

Pages.PageRenderer.RenderSession

One request's lifetime and slots, shared by every layer of its chain.

PropertyIsStreaming

Whether this request has committed its response and is holding a stream slot.

PropertyStreamOutcome

How the stream ended, for the endpoint's log line.

MethodComplete(bool clientLeft)

Marks the stream as ended normally, or by the client leaving.

Parameters

clientLeft
Whether the request was aborted.

MethodFail()

Marks the stream as ended by a page fault.

MethodTruncated()

Marks the stream as ended by the clock that fired during its last write.

PropertyTokenCancelled

Whether the render's deadline has fired.

MethodRenderAsync(PagePath path, Pages.SimpleContext context, Pages.PageSelection selection)

Renders one layer of the chain under this session's lifetime.

Parameters

path
The layer's canonical key.
context
The context the layer writes to.
selection
Which representation to render, or null for the page's own.

MethodDisposeAsync()

Inherited from IAsyncDisposable.DisposeAsync.

Pages.PageRequestSnapshot

Reads the live ASP.NET request once, into the plain values a page sees.

MethodCreate(HttpRequest request)

Takes the snapshot a page runs against.

Parameters

request
The request to read.

Returns

The request values; the form is empty when the request is not a form post.

Pages.PageResponseState

What a page has asked the response to be, before it is built.
Collects the status, content type, headers, redirect and script policy so the response is shaped once, when the handler returns or at the first flush. The commit and the layout rule are not here: they are about who is calling, so they stay on the context, which validates before it delegates.

MethodPageResponseState(string contentType)

Creates the response a page will ask for.

Parameters

contentType
The media type the page's key names.

PropertyContentType

The content type the response will be sent with.

PropertyLocation

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

MethodSetStatus(int status)

Sets the status code the response will be sent with.

Parameters

status
The code to send, between 100 and 599.

MethodSetContentType(string contentType)

Sets the content type the response will be sent with.

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 the response to load same-origin scripts.

MethodRedirect(string location, int status)

Redirects instead of writing a body.

Parameters

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

MethodToResponse()

What the page asked the response to be.
Every page that runs code is no-store: it can keep per-visitor state, so its body has no business in a shared cache and no business inviting a conditional request. The host writes the same header after the page's own, so this is the default rather than the last word.

Pages.PageResponseWriter

Applies a page's response, once, for both the buffered and the streamed path.
The two paths differ only in when the response starts and whether the body is written in one piece. Status, content type, the page's headers, no-store, the script policy and the session cookie are one decision and must not drift.

MethodApplyAsync(HttpContext context, PageResponse response, Pages.PageEnvironment environment, Pages.PageSessionRequest session, bool start, CancellationToken cancellationToken)

Applies the response's status, content type, headers and cookies.

Parameters

context
The response being written.
response
What the page asked the response to be.
environment
The session the cookie belongs to.
session
The visitor's session for this request.
start
Whether to start the response after applying it.
cancellationToken
Cancels the start.

Returns

Whether the response is a redirect, which has no body.

MethodAllowsBody(PageResponse response)

Whether a response with this status may carry a body.

Parameters

response
What the page asked the response to be.

Pages.PageRevision

One immutable saved revision: a template, and the image built from it.

Pages.PageRevisionSummary

One row of a page's revision history.

MethodPageRevisionSummary(string, DateTimeOffset, string, Pages.PageImageState, bool)

One row of a page's revision history.

Pages.PageRevisionTemplate

A stored revision's template, for the editor and its diff.

MethodPageRevisionTemplate(PagePath, string, DateTimeOffset, string, Pages.PageImageState, string)

A stored revision's template, for the editor and its diff.

Pages.PageSeedInstaller

The rule for comparing a bundled seed with the live head, and for installing it.
The emergency restore and the routine apply ask the same questions of the same pack — what does the store hold, and what would writing the seed do — so they ask them here. Every write goes through SaveSeedAsync, which records the seed hash as the page's anchor.

MethodPlanAsync(Editor.PageEditor pages, Pages.PageSeeds seeds, CancellationToken cancellationToken)

Reads every seed and compares it with the live head.

Parameters

pages
The page store.
seeds
The pack this release ships.
cancellationToken
Cancels the reads.

MethodInstallAsync(Editor.PageEditor pages, Pages.PageSeedInstaller.SeedPlan seed, CancellationToken cancellationToken)

Installs one seed through the ordinary saver, recording the seed it installed.
A save with errors is still stored, so the outcome says so rather than failing; an exception is the caller's to catch.

Parameters

pages
The page store.
seed
The plan entry to write.
cancellationToken
Cancels the write.

Pages.PageSeedInstaller.SeedOutcome

What one seed's install did.

Pages.PageSeedInstaller.SeedPlan

One seed, its bundled source, and what the store holds now.

MethodSeedPlan(PagePath Path, string Source, string SeedHash, PageSeedSummary Summary, bool HoldsSeed)

One seed, its bundled source, and what the store holds now.

Parameters

Path
The page's key.
Source
The bundled source.
SeedHash
The hash of the bundled source.
Summary
The verdict and the actions it permits.
HoldsSeed
Whether the live content already equals the bundled source.

PropertyPath

The page's key.

PropertySource

The bundled source.

PropertySeedHash

The hash of the bundled source.

PropertySummary

The verdict and the actions it permits.

PropertyHoldsSeed

Whether the live content already equals the bundled source.

Pages.PageSeedInstaller.SeedResult

One seed and the outcome of trying to install it.

MethodSeedResult(PagePath Path, PageSeedSummary Was, Pages.PageSeedInstaller.SeedOutcome Outcome, string Hash)

One seed and the outcome of trying to install it.

Parameters

Path
The page's key.
Was
What the store held before.
Outcome
What this run did.
Hash
The revision it stored, or the current head when nothing was written.

PropertyPath

The page's key.

PropertyWas

What the store held before.

PropertyOutcome

What this run did.

PropertyHash

The revision it stored, or the current head when nothing was written.

Pages.PageSeeds

The pages this release ships, read from the seed folder once per process.

The pack is a folder beside the assembly, because that is where the build copies Pages/Seeds. Reading it once here removes the directory walk every SeedSourceAsync lookup used to do, and gives the seeder, the page list, the shell's restore and the seeds command one account of what this release carries.

A key is the file's path under the folder, so a seed in a subtree is seeded at its subtree's key: _lib/document is /_lib/document.

MethodPageSeeds(string directory)

Reads every seed in a folder.

Parameters

directory
The folder the build copies the seed files into.

Exceptions

ArgumentException
The folder is blank.

PropertyFiles

Every seed, in ordinal key order.

PropertyPaths

Every seed's key, in ordinal order.

MethodContains(PagePath path)

Whether this release ships a seed for a key.

Parameters

path
The canonical key.

MethodFind(PagePath path)

One seed, or null when this release does not ship it.

Parameters

path
The canonical key.

MethodSource(PagePath path)

The source this release ships for a key, or null when it ships none.

Parameters

path
The canonical key.

Pages.PageSelection

A revision the caller has already read, and why it was read.

MethodPageSelection(Pages.PageTemplate Page, bool IsHistorical)

A revision the caller has already read, and why it was read.

Parameters

Page
The revision to run.
IsHistorical
Whether the revision came from a ?v= hash rather than the live head. A historical row is fixed, so a compile is stored against it and the head is never read again.

PropertyPage

The revision to run.

PropertyIsHistorical

Whether the revision came from a ?v= hash rather than the live head. A historical row is fixed, so a compile is stored against it and the head is never read again.

Pages.PageSessionCaps

The per-value and whole-session caps one kind of visitor's session obeys.

MethodPageSessionCaps(int MaxValueBytes, int MaxKeys, int MaxTotalBytes)

The per-value and whole-session caps one kind of visitor's session obeys.

Parameters

MaxValueBytes
The largest one JSON value may be, in bytes.
MaxKeys
The most keys one session may hold.
MaxTotalBytes
The most bytes a session's keys and values may total.

PropertyMaxValueBytes

The largest one JSON value may be, in bytes.

PropertyMaxKeys

The most keys one session may hold.

PropertyMaxTotalBytes

The most bytes a session's keys and values may total.

PropertyAnonymous

The anonymous caps the shipped configuration carries.

PropertySignedIn

The signed-in caps the shipped configuration carries.

MethodRead(Configuration.ConfigurationReader reader, Pages.PageSessionCaps recommended)

Reads one kind's caps.

Parameters

reader
The kind's configuration, opened on its own section.
recommended
The caps the shipped configuration carries, for the messages.

Exceptions

A value is missing or unusable.

Pages.PageSessionCleanupService

Drops page sessions that expired, and trims the table when it is over its cap.
A timer rather than a sweep on a request: a visitor should not pay for housekeeping, and a site whose visitors stop arriving still needs its rows to go. A sweep that fails is logged and retried on the next tick rather than taking the host down.

MethodPageSessionCleanupService(Pages.IPageSessionStore, ILogger<Pages.PageSessionCleanupService>)

Drops page sessions that expired, and trims the table when it is over its cap.
A timer rather than a sweep on a request: a visitor should not pay for housekeeping, and a site whose visitors stop arriving still needs its rows to go. A sweep that fails is logged and retried on the next tick rather than taking the host down.

Pages.PageSessionEntry

One visitor's session: the identity, its account and when it last moved.
The session id is the value of the shell's cookie and is never chosen by a page. Account is the normalised user name the session belongs to, or null for an anonymous visitor.

PropertyAccount

The normalised account name, or null for an anonymous visitor.

PropertyCreatedAt

When the row was minted, in UTC.
A DateTime rather than a DateTimeOffset because SQLite cannot order by an offset and eviction is an order: every timestamp this store writes is UTC.

PropertyUpdatedAt

When the row was last read or written, in UTC. Reading slides the idle timer.

Pages.PageSessionOptions

Bounds what one visitor's session may cost.
The caps are per session, not per page, so one page's keys can use the room another would have had. An anonymous visitor gets the smaller set because a public page that writes on every visit lets any client mint a row; a signed-in visitor has already been identified. Every value comes from Pages:Session, and the key length is Pages:Storage:MaxKeyChars, the same rule page state uses.

PropertyMaxKeyChars

The longest key a page may use.

PropertyAnonymous

The caps an anonymous visitor's session obeys.

PropertySignedIn

The caps a signed-in visitor's session obeys.

PropertyAnonymousIdle

How long an anonymous session survives without a visit.

PropertySignedInIdle

How long a signed-in session survives without a visit.

PropertyMaxLiveSessions

The most live sessions the site keeps.

PropertyCommandTimeoutSeconds

How long one session command may run.

PropertyCommandTimeout

The command timeout as a time span.

MethodFor(string account)

The caps for a session belonging to account.

Parameters

account
The normalised account name, or null.

MethodIdleFor(string account)

How long a session belonging to account survives without a visit.

Parameters

account
The normalised account name, or null.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Session.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Session into the caller's report.

Parameters

reader
A reader opened on Pages:Session, which the caller completes.

Pages.PageSessionRequest

One request's session id and whether its row exists yet.
The page endpoint resolves this once and every layer of the chain shares it, so two layers cannot see different sessions. A row is minted on the first write rather than on the request, which is what keeps a page that never uses the session from costing a visitor a cookie or a row.

MethodPageSessionRequest(string, string, bool, bool)

One request's session id and whether its row exists yet.
The page endpoint resolves this once and every layer of the chain shares it, so two layers cannot see different sessions. A row is minted on the first write rather than on the request, which is what keeps a page that never uses the session from costing a visitor a cookie or a row.

PropertyId

The value the cookie carries, whether the row exists yet or not.

PropertyAccount

The normalised account name of the request, or null.

PropertyPresented

Whether the visitor presented this id in a cookie.

PropertyExists

Whether the session row exists.

PropertyMinted

Whether this request created the row.

PropertyNeedsCookie

Whether the response has to carry a cookie so the browser learns the new id.

MethodEnsureAsync(Pages.IPageSessionStore store, CancellationToken cancellationToken)

Mints the row if this is the request's first write.

Parameters

store
Where the row lives.
cancellationToken
Cancels the work.

Exceptions

ArgumentException
The site has no room for another session.

MethodTouchAsync(Pages.IPageSessionStore store, CancellationToken cancellationToken)

Slides the idle timer, at most once per request.

Parameters

store
Where the row lives.
cancellationToken
Cancels the work.

MethodGetStringAsync(Pages.IPageSessionStore store, string pagePath, string key, CancellationToken cancellationToken)

Reads a string the shell wrote.

Parameters

store
Where the value lives.
pagePath
The canonical page key the value belongs to.
key
The key to read.
cancellationToken
Cancels the read.

Returns

The stored string, or null when the key is absent.

MethodSetTextAsync(Pages.IPageSessionStore store, Pages.PageSessionOptions options, string pagePath, string key, string text, CancellationToken cancellationToken)

Writes a value for the shell's own use, minting the session when it does not exist.

Parameters

store
Where the value lives.
options
The caps the session obeys.
pagePath
The canonical page key the value belongs to.
key
The key to write.
text
The text to store.
cancellationToken
Cancels the write.

MethodDeleteTextAsync(Pages.IPageSessionStore store, string pagePath, string key, CancellationToken cancellationToken)

Removes a value the shell wrote.

Parameters

store
Where the value lives.
pagePath
The canonical page key the value belongs to.
key
The key to remove.
cancellationToken
Cancels the write.

Returns

Whether the key existed.

Pages.PageSessionResolver

Resolves the request's session once, before any layer sees it.

MethodResolveAsync(HttpContext context, Pages.IPageSessionStore store, Authentication.PageSessionCookieOptions options, PageUser user, CancellationToken cancellationToken)

Finds, discards or starts the session for this request.
A row that belongs to an account is only honoured for that account: a stale cookie cannot inherit the account's caps or read what an owner's page left behind. A mismatch deletes the row and starts a fresh session.

Parameters

context
The request being answered.
store
Where session rows live.
options
The cookie's name.
user
The signed-in account, or null.
cancellationToken
Cancels the work.

Returns

The resolved session, cached on the request so every caller sees one.

Pages.PageSessionScope

One page's IPageSession, bound to that page's key.
Isolation is structural rather than a check: every write, delete and listing uses the page's own path, and there is no overload that names another. Reading is open, because a page showing what another page left it is the point; the path is normalised before use, so a traversal cannot name something else.

MethodPageSessionScope(PagePath, Pages.IPageSessionStore, Pages.PageSessionOptions, Pages.PageSessionRequest, bool, bool, Pages.PageCommitState)

One page's IPageSession, bound to that page's key.
Isolation is structural rather than a check: every write, delete and listing uses the page's own path, and there is no overload that names another. Reading is open, because a page showing what another page left it is the point; the path is normalised before use, so a traversal cannot name something else.

MethodTryGetValueAsync<T>(string)

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

Inherited from IPageSession.TryGetValueAsync<T>.

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, string)

Reads a value another page wrote.

Inherited from IPageSession.TryGetValueAsync<T>.

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, T)

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

Inherited from IPageSession.SetAsync<T>.

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)

Removes one of this page's keys.

Inherited from IPageSession.DeleteAsync.

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.

Inherited from IPageSession.KeysAsync.

Returns

The keys, in ordinal order.

MethodAllKeysAsync()

Lists every key this visitor's session holds, from every page.

Inherited from IPageSession.AllKeysAsync.

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.

Pages.PageSessionSweep

What one session sweep removed, by kind.

MethodPageSessionSweep(int Expired, int AnonymousEvicted, int SignedInEvicted)

What one session sweep removed, by kind.

Parameters

Expired
Sessions past their idle window.
AnonymousEvicted
Anonymous sessions removed to get back under the live-session cap.
SignedInEvicted
Signed-in sessions removed to get back under the live-session cap.

PropertyExpired

Sessions past their idle window.

PropertyAnonymousEvicted

Anonymous sessions removed to get back under the live-session cap.

PropertySignedInEvicted

Signed-in sessions removed to get back under the live-session cap.

Pages.PageSessionValueEntry

One key of one page's state inside one visitor's session.
The page path is required on every row, including the shell's own keys. There is no null or empty area, which is also what keeps SQLite's NULL-is-distinct rule out of the unique key.

PropertyValue

The value as JSON. A stored null is the text null, not a missing row.

Pages.PageStateEntry

One key of one page's state, with its value stored as JSON.
There is no foreign key to Pages.PageHead: SQLite's enforcement depends on the connection, and the deletes that keep state from outliving a page are explicit anyway. Keeping the relationship out of the schema avoids a migration-order dependency for no gain.

PropertyValue

The value as JSON. A stored null is the text null, not a missing row.

PropertyUpdatedAt

When the row was last written; informational, and taken from the registered clock.

Pages.PageStateKey

The rule a page's state key obeys, shared by a page's own write and an imported archive.
A key is 1 to MaxKeyChars characters with no control characters. An archive is validated against this before anything is staged, so an import cannot store a key a page could not have written itself.

MethodIsValid(string key, int maxChars)

Whether key may name a state value.

Parameters

key
The key to test.
maxChars
The configured maximum length.

MethodValidate(string key, int maxChars)

Throws when key may not name a state value.

Parameters

key
The key to check.
maxChars
The configured maximum length.

Exceptions

ArgumentException
The key is empty, too long, or carries a control character.

Pages.PageStateValue

One key of one page's state, with its value as the stored JSON text.

MethodPageStateValue(string Key, string Value)

One key of one page's state, with its value as the stored JSON text.

Parameters

Key
The key, 1–MaxKeyChars characters, no control characters.
Value
The value as JSON. A stored null is the text null, not a missing row.

PropertyKey

The key, 1–MaxKeyChars characters, no control characters.

PropertyValue

The value as JSON. A stored null is the text null, not a missing row.

Pages.PageStorageOptions

Bounds what one page's key/value store may cost.
Every value comes from Pages:Storage, and MaxPageBytes must be at least MaxValueBytes so a single value at the per-value limit still fits an empty page.

PropertyMaxKeyChars

The longest key a page may use.

PropertyMaxValueBytes

The largest one JSON value may be, in bytes.

PropertyMaxKeysPerPage

The most keys one page may hold.

PropertyMaxPageBytes

The most bytes one page's keys and values may total.

PropertyCommandTimeoutSeconds

How long one storage command may run.

PropertyCommandTimeout

The command timeout as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Storage.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Storage into the caller's report.

Parameters

reader
A reader opened on Pages:Storage, which the caller completes.

Pages.PageStorageScope

One page's IPageStorage, bound to that page's key.
The only handle a page ever gets, so it cannot name another page: isolation is structural rather than a check. Keys and values are validated here, and every per-page cap is enforced by the store in the same statement as the write.

MethodPageStorageScope(PagePath, Pages.IPageStateStore, Pages.PageStorageOptions, bool)

One page's IPageStorage, bound to that page's key.
The only handle a page ever gets, so it cannot name another page: isolation is structural rather than a check. Keys and values are validated here, and every per-page cap is enforced by the store in the same statement as the write.

MethodTryGetValueAsync<T>(string)

Reads a value and reports whether the key exists.

Inherited from IPageStorage.TryGetValueAsync<T>.

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, T)

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

Inherited from IPageStorage.SetAsync<T>.

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)

Removes a key.

Inherited from IPageStorage.DeleteAsync.

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.

Inherited from IPageStorage.KeysAsync.

Returns

The keys, in ordinal order.

Pages.PageTemplate

A page's template, the image built from it, and the revision it will be saved as.

MethodPageTemplate(PagePath Path, string Template, Pages.PageImage Image)

Builds a revision with a fresh id, timestamp and hash.

Parameters

Path
The canonical key the page is stored under.
Template
The template text.
Image
The image built from the template, or null when this build has never compiled it. A template without one is compiled on its next request.

PropertyKind

What the revision is for — text, a page, or a library — or null when it has never been generated. A text revision is served from source and never compiled; a library is checked and never run.

PropertySeedHash

The seed this write is installing, or null when the write is not a seed write. The store records it as the page's anchor and leaves the recorded one alone otherwise.

MethodNewRevision(PagePath path, string source, Pages.PageImage image, string runtimeId, string seedHash)

Builds a revision around a template and the image compiled from it.

Parameters

path
The canonical key the page is saved under.
source
The template text.
image
The compiled image, or null when there is none.
runtimeId
The build that compiled the image.
seedHash
The seed this write is installing, or null when it is not a seed write. Only this value is recorded as the page's anchor; every other write leaves the recorded one alone.

Returns

A revision with a fresh id, timestamp and hash. An editor save and an import both build revisions here, so the two paths cannot produce a row shaped differently.

Pages.PageWrap

One page that will wrap the page that declared it.

MethodPageWrap(PagePath Key, PageRequest Request, bool IsDefault)

One page that will wrap the page that declared it.

Parameters

Key
The wrapper's canonical key.
Request
The request the wrapper runs against.
IsDefault
Whether the page asked for the site's layout rather than naming one, which is what decides whether a wrapper that cannot be served is skipped or is an error.

PropertyKey

The wrapper's canonical key.

PropertyRequest

The request the wrapper runs against.

PropertyIsDefault

Whether the page asked for the site's layout rather than naming one, which is what decides whether a wrapper that cannot be served is skipped or is an error.

Pages.PageWriteAction

The one write a render may make, shared by its content layer and every embedded layer.
A render writes once: two writes in one page are refused today, and a listing that embeds a self-saving widget would quietly make several if each layer owned its own counter.

PropertyHasActed

Whether this render has already written.

MethodAct()

Records that this render has now written.

Pages.PageWritesScope

The store's write capability, bound to one render.

The host offers this to every content layer and never to a layout. Which page asked is not part of the check: the authority is the signed-in visitor, and the reserved keys are the only pages the shell keeps out of reach.

Authority is asymmetric with the catalog. An anonymous render is refused with a UserFacingException before anything is compiled or stored; a HEAD, an ended render, a second write and a reserved key are page bugs and throw InvalidOperationException. The key itself is the page's answer through Resolve, so a typo in a query value is a message the page renders.

The two saves share one action: a page that saved itself cannot then edit another page in the same render. A save is conditional on the head hash the form carried when it names a key, and a save that has begun is not abandoned: the render's deadline bounds the wait for a compile slot, not the author's edit (`pages-a-page-may-save-itself`).

MethodPageWritesScope(PagePath, Editor.PageEditor, PageUser, bool, Pages.ReservedPaths, Pages.PageSeeds, Pages.PageWriteAction)

The store's write capability, bound to one render.

The host offers this to every content layer and never to a layout. Which page asked is not part of the check: the authority is the signed-in visitor, and the reserved keys are the only pages the shell keeps out of reach.

Authority is asymmetric with the catalog. An anonymous render is refused with a UserFacingException before anything is compiled or stored; a HEAD, an ended render, a second write and a reserved key are page bugs and throw InvalidOperationException. The key itself is the page's answer through Resolve, so a typo in a query value is a message the page renders.

The two saves share one action: a page that saved itself cannot then edit another page in the same render. A save is conditional on the head hash the form carried when it names a key, and a save that has begun is not abandoned: the render's deadline bounds the wait for a compile slot, not the author's edit (`pages-a-page-may-save-itself`).

MethodResolve(string)

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

Inherited from IPageWrites.Resolve.

Parameters

key
The text the page was given.

Returns

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

MethodSeedSourceAsync(string)

Reads the source this release ships for a seed.

Inherited from IPageWrites.SeedSourceAsync.

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)

Saves this page's own source as a new revision.

Inherited from IPageWrites.SaveAsync.

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, string, string)

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

Inherited from IPageWrites.SaveAsync.

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.

MethodDeleteAsync(string)

Tombstones a page, keeping its history.

Inherited from IPageWrites.DeleteAsync.

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, string, string)

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

Inherited from IPageWrites.RestoreRevisionAsync.

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.

MethodAdoptSeedAsync(string)

Records a seed as installed without storing a revision.

Inherited from IPageWrites.AdoptSeedAsync.

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.

MethodInstallSeedAsync(string, string)

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

Inherited from IPageWrites.InstallSeedAsync.

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.

Pages.ReadBudget

The template allowance one request's whole layout chain shares.
The cap names the render rather than the layer, so a layout must not double the allowance simply because there are two layers reading under it. A read that would go over is refused rather than clamped, because half a template is a misleading answer.

MethodReadBudget(int maxChars)

Creates the counter for one render.

Parameters

maxChars
How much template one render may pull in.

PropertyMaxChars

How much template one render may pull in.

MethodTryCharge(int chars)

Charges one template against the budget.

Parameters

chars
The template's length.

Returns

Whether the read fits; nothing is charged when it does not.

Pages.RenderBoundCapability

The state every capability the render can stop shares: its deadline and its abandonment.
A page's task and the abandoning thread can be different threads, so the flag is read with Volatile rather than through a lock the page never takes.

PropertyIsAbandoned

Whether the render was given up on.

PropertyDeadline

The render's deadline, which ends a call that outlives it.

MethodAttachDeadline(CancellationToken)

Gives the capability the render's deadline.

Inherited from Pages.IRenderBoundCapability.AttachDeadline.

Parameters

deadline
The deadline's token; it outlives this use of it.

MethodAbandon()

Stops accepting work, because the render was given up on.

Inherited from Pages.IRenderBoundCapability.Abandon.

Pages.RenderFetchBudget

The requests one render may still make, shared by every layer.
The cap names the render rather than the layer, so a layout must not double the allowance simply because there are two layers rendering under it.

MethodRenderFetchBudget(int maxRequests)

Creates the counter for one render.

Parameters

maxRequests
How many requests the whole render may make.

MethodTryTake()

Spends one request, when the render has one left.

Returns

true when the caller may make the request.

Pages.RenderLifetime

The two clocks and the slot a page holds while it runs, and how its stream ended.

Before the first flush this is the render's absolute budget and the render slot. From the commit it is the stream's silence clock, re-armed by every flush, and an absolute ceiling, held against a stream slot instead. One owner for the whole of it is what keeps the slot accounting from drifting between the context, the renderer and the endpoint.

The deadline is one linked source for the request and the budget, so the page's waits, its capabilities and the renderer's expiry all stop at the same moment. The source outlives an abandoned page: the page's continuation disposes it when it finally stops, because disposing it under a running page would pull the token out from under it.

MethodRenderLifetime(Pages.PageBudget budget, PagePath path, Pages.PageMetrics metrics, CancellationTokenSource deadline)

Starts the lifetime with the render slot already taken.

Parameters

budget
The slots the lifetime releases and takes.
path
The page the request asked for, for the metric and the log.
metrics
Where the stream's own duration is recorded.
deadline
The linked source already armed with the render's budget.

PropertyToken

The deadline every layer and capability in this render waits against.

PropertyIsStreaming

Whether this render has committed and is holding a stream slot.

PropertyOutcome

How the stream ended, or completed while it is still running.

MethodOnCommit(Action onCommit)

Registers what records the render's own duration at the commit.

Parameters

onCommit
The callback; it runs once, before the response starts.

MethodRegisterCleanup(Func<Task> cleanup)

Registers asynchronous resource cleanup at the end of the render.

Parameters

cleanup
The cleanup operation to await when the render ends.

MethodBeginStreamAsync()

Moves the render from its budget to the stream's clocks.

Returns

A task that completes when the stream slot is held.

Exceptions

Every stream slot is taken; nothing is committed.

MethodReArm()

Restarts the silence clock after a flush.

MethodComplete(bool clientLeft)

Marks the stream as ended normally, or by the client leaving.

Parameters

clientLeft
Whether the request was aborted rather than the page returning.

MethodFail()

Marks the stream as ended by a page fault.

MethodTruncated()

Marks the stream as ended by the clock that fired while the last bytes were written.

MethodAbandon(bool clientLeft)

Records that the render gave up on the page and why.

Parameters

clientLeft
Whether the visitor left rather than the deadline firing.

MethodDisposeAsync()

Releases the slots and records the stream's lifetime.

MethodDisposeDeadline()

Disposes the deadline once an abandoned page has finally stopped.

Pages.RenderOptions

Bounds what one page render may cost the process that runs it.
Every value is read from Pages:Render and none has a fallback: a missing or unusable value stops the site at startup. The deadline is the whole budget for a request: queueing for a slot counts against it, because a visitor is waiting either way.

FieldMaximumLayoutDepth

The deepest chain a configuration may ask for.

FieldMaximumEmbedDepth

The deepest embed a configuration may ask for.

PropertyTimeoutSeconds

The whole budget for one render, including the wait for a slot.

PropertySlots

Page renders allowed to run at once; further requests wait without a thread.

PropertyMaxBodyChars

How much body a page may buffer before it is refused. It stops at the first flush: a streaming page's body is on the wire and is not charged after its response has been committed.

PropertyAbandonedLimit

Abandoned renders alive at once before the health check reports unhealthy.

PropertyMaxLayoutDepth

How many layouts one page may be wrapped in, up to MaximumLayoutDepth.

PropertyMaxEmbedDepth

How deep embeds may nest below the layer that is running, up to MaximumEmbedDepth.
Chosen apart from MaxLayoutDepth because a widget is not chrome: a listing that draws each row through a page needs depth the layout chain should not grant.

PropertyMaxEmbeds

How many embeds one request may make, which bounds a listing's fan-out.
Depth alone lets one listing embed a thousand siblings under one slot and one deadline.

PropertyTimeout

The budget as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Render.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Render into the caller's report.

Parameters

reader
A reader opened on Pages:Render, which the caller completes.

Pages.RenderResult

The outcome of rendering a page.

MethodRenderResult(Pages.RenderStatus Status, IReadOnlyList<PageDiagnostic> Diagnostics)

The outcome of rendering a page.

Parameters

Status
What rendering did.
Diagnostics
The compiler's author-facing diagnostics when Status is CompileFailed; empty otherwise.

PropertyStatus

What rendering did.

PropertyDiagnostics

The compiler's author-facing diagnostics when Status is CompileFailed; empty otherwise.

PropertyIsSource

Whether the body is the stored source, served without compiling or executing it.

PropertyNotFound

No page is stored under the requested key.

PropertyRendered

The page's handler ran.

PropertyFromSource

The revision has no code, so its stored source is the body.

PropertyTimedOut

The page outran its budget; its output was discarded.

MethodCompileFailed(IReadOnlyList<PageDiagnostic> diagnostics)

The page does not compile.

Parameters

diagnostics
The compiler's author-facing diagnostics.

Pages.RenderStatus

What rendering a page did.

FieldRendered

The page's handler ran; its output is in the request's context.

FieldCompileFailed

The page does not compile; its diagnostics explain why.

FieldNotFound

No page is stored under the requested key.

FieldTimeout

The page outran its execution budget, so the answer was given up on.

Pages.ReservedPaths

The page keys the site's own routes already own.

Entries are matched as prefixes, not exactly: /admin/scrub/{**path} shadows everything beneath it, so a page called /admin/scrub/anything is as unreachable as one called /admin/scrub.

The list is the shell's own route table, not configuration: a route exists because the site's code answers it, and a shorter list could only let a stored page shadow a route such as /login (shell-reserved-keys-are-an-invariant).

PropertyDefault

The keys the shell's route table names.

MethodReservedPaths(IEnumerable<string> paths)

Creates the list from the configured keys.

Parameters

paths
The configured keys, which must hold at least one.

Exceptions

ArgumentException
No key was given, so no route would be reserved.

PropertyKeys

The reserved keys themselves, in the route table's order, as canonical paths.

MethodIsReserved(PagePath path)

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

Parameters

path
The canonical key to test.

MethodMatchingPrefix(PagePath path)

The reserved key that owns this one, so a key beneath a route can name the route.
The most specific key wins, so a read beneath /admin/scrub names that route rather than the /admin root above it.

Parameters

path
The canonical key to test.

Pages.SeedCommands

The seed command that runs before the web host starts.

The pack is edited in production and the repository falls behind it. The command's job is only to get the store's bytes out and into the working tree; git is the merge tool and git diff is the review. Its result is on standard output — a table for list, a tar for pull — and everything said about the run is on standard error, so a log line can never land inside the tar.

pull writes only the keys whose stored source differs from the file this release ships. --all writes every key the store has live, and --missing names the keys the pack ships that the store does not have live: a pull cannot fix those, and an install or a restore must. Nothing is deleted; deletion is git's job.

FieldName

The command word that selects the seed tool.

MethodIsCommand(string[] args)

Whether the process arguments are a seed command.

Parameters

args
The process arguments.

MethodRunAsync(string[] args, IServiceProvider services, Stream output, TextWriter error, CancellationToken cancellationToken)

Runs a seed command against the application's services.

Parameters

args
The arguments after seeds.
services
The application's service provider.
output
The stream the command's result is written to, which is standard output.
error
Where the command says what it did, which is standard error.
cancellationToken
Cancels the command.

Returns

The process exit code.

Pages.SeedFile

One seed: its key, its path under the seed folder, its exact source and its hash.

MethodSeedFile(PagePath Path, string Name, string Source, string Hash)

One seed: its key, its path under the seed folder, its exact source and its hash.

Parameters

Path
The canonical page key the seed installs.
Name
The file's path under the seed folder, with / separators.
Source
The file's text, exactly as it will be stored.
Hash
The content hash of Source, which is what a seed write records.

PropertyPath

The canonical page key the seed installs.

PropertyName

The file's path under the seed folder, with / separators.

PropertySource

The file's text, exactly as it will be stored.

PropertyHash

The content hash of Source, which is what a seed write records.

Pages.SeedVerdictWords

The words a seed verdict is reported in, beside Pages.PageImageStatus.
The comparison is the core's; the sentence is the host's, because it is the host that knows what it will and will not write. A page renders these words and offers the actions the flags permit, so the listing, the terminal and the admin views cannot describe one row three ways.

MethodDescribe(SeedComparison comparison, string shipped)

A live page's summary, from its comparison.

Parameters

comparison
The comparison of R, S and H.
shipped
The hash this release ships, or null when it ships none.

MethodNew()

A key this release ships that the store does not have.

MethodDeleted()

A tombstone at a key this release still ships.

Pages.SimpleContext

The only IContext a page ever runs against.

The request side of the contract: what the page can read and ask for, and the wiring that gives it a Pages.SimpleResponse to write into. The rules about the response live there.

This is the only type a page's logging goes through, and the category and its scope are operator-facing: changing them breaks configured filters and log queries.

PropertyResponse

The response this layer writes into.

MethodSimpleContext(ILoggerFactory loggerFactory, PageRequest request, CancellationToken aborted, StringWriter writer, Pages.PageCapabilities capabilities, PageContentTypes contentTypes, int maxBodyChars, string user, PageUser loginRedirect, string antiforgeryField, Func<string> path, PagePath role, Pages.PageLayerRole bodyBudget, Pages.BodyBudget assetUrl, Func<string, string> editorPath, Pages.PageCommitState commitState, Pages.IPageBodySink bodySink, Func<string, bool> wouldWrap)

Creates the context a page runs against.

Parameters

loggerFactory
Creates the one logger every page writes through.
request
The request snapshot.
aborted
The token from the request being served.
writer
The buffer the body is written to.
capabilities
The capabilities this layer offers.
contentTypes
The media type the page's key names.
maxBodyChars
How much body this layer may write when no chain budget is given.
user
The signed-in account, or null for an anonymous visitor.
loginRedirect
Where RedirectToLogin sends an anonymous visitor.
antiforgeryField
Builds the hidden antiforgery input, or null when the page must get nothing.
path
The layer's own key, which is the request's path for the content layer.
role
What this layer is. Only the content owns the response: a layout or an embedded page is markup, so status, content type and headers are ignored, and an embedded page's redirect refuses because it has no response to redirect.
bodyBudget
The allowance the whole chain shares; a layer on its own gets one of its own.
assetUrl
Resolves a link against the request's asset map, or null when the render has no map and every link is left as written.
editorPath
The editor key a layout's remedy links to.
commitState
Whether this layer has committed its response, shared with the capabilities that would need to set a header after the commit.
bodySink
Where a flushing page writes, or null when it cannot stream.
wouldWrap
Whether a response of this content type would be wrapped in a layout, in which case it cannot stream.

PropertyRequest

The request the page is running against.

Inherited from IContext.Request.

PropertyPath

The canonical key of the page being rendered.

Inherited from IContext.Path.

PropertyEditorPath

The canonical key of the site's editor page, so a page can link to it.

Inherited from IContext.EditorPath.

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.

Inherited from IContext.User.

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.

Inherited from IContext.Aborted.

PropertyCapabilities

The capabilities this render offers.

Inherited from IContext.Capabilities.

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>.

MethodAttachLifetime(Pages.RenderLifetime lifetime)

Gives the page the render's lifetime, so its I/O and its stream share one clock.

Parameters

lifetime
The lifetime the renderer opened for this request.

MethodAbandon()

Stops the page writing, once its render has been given up on.
The page cannot be stopped, so this is what keeps it from filling the buffer — or racing the response — after the site has answered without it.

MethodLog(string)

Logs a message at information level.

Inherited from IContext.Log.

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)

Logs a message at warning level.

Inherited from IContext.LogWarning.

Parameters

message
The message to log.

MethodLogError(string)

Logs a message at error level.

Inherited from IContext.LogError.

Parameters

message
The message to log.

MethodAssetUrl(string)

Versions a same-origin link when the page it names is a live asset.

Inherited from IContext.AssetUrl.

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.

Pages.SimpleResponse

The only IPageResponse a page ever writes into.

What the page asks for is collected by Pages.PageResponseState and Pages.PageBody; this type is the page's door to them and the rules about who may ask. The commit gate, the layer role, the stream refusals and the antiforgery token are here because each answers "may this layer set that?" about the response.

The response is applied once the handler has returned, or at the first flush, so a page that throws leaves nothing half-sent.

MethodSimpleResponse(Pages.PageResponseState response, Pages.PageBody body, PagePath path, PageRequest request, string loginRedirect, Pages.PageLayerRole role, ILogger logger, Func<string> antiforgeryField, Func<string, bool> wouldWrap)

The only IPageResponse a page ever writes into.

What the page asks for is collected by Pages.PageResponseState and Pages.PageBody; this type is the page's door to them and the rules about who may ask. The commit gate, the layer role, the stream refusals and the antiforgery token are here because each answers "may this layer set that?" about the response.

The response is applied once the handler has returned, or at the first flush, so a page that throws leaves nothing half-sent.

Parameters

response
What the page asked the response to be.
body
The body the page writes, and its way onto the wire.
path
The layer's own key, which the refusals name.
request
The request, for the method a sign-in redirect answers with.
loginRedirect
Where RedirectToLogin sends an anonymous visitor.
role
What this layer is. Only the content owns the response: a layout or an embedded page is markup, so status, content type and headers are ignored, and an embedded page's redirect refuses because it has no response to redirect.
logger
Where a layer that does not own the response reports an ignored setting.
antiforgeryField
Builds the hidden antiforgery input, or null when the page must get nothing.
wouldWrap
Whether a response of this content type would be wrapped in a layout, in which case it cannot stream.

MethodToResponse()

What the page asked the response to be.

MethodGetBody()

The body written so far.

PropertyIsCommitted

Whether the first flush has committed the response.

MethodCompleteAsync()

Writes whatever the page left buffered after its last flush.

MethodAttachLifetime(Pages.RenderLifetime lifetime)

Gives the body the render's lifetime, so its I/O and its stream share one clock.

Parameters

lifetime
The lifetime the renderer opened for this request.

MethodAbandon()

Stops the page writing, once its render has been given up on.

MethodWrite(string)

Exceptions

ArgumentNullException
The page passed null.

MethodWriteRaw(string)

Exceptions

ArgumentNullException
The page passed null.

MethodFlushAsync()

Exceptions

InvalidOperationException
This render cannot stream, the page is a layout or an embedded page, it has redirected, or it has declared a wrapper.

MethodSetStatus(int)

Sets the response status code.

Inherited from IPageResponse.SetStatus.

Parameters

status
The code to send, between 100 and 599.

MethodSetContentType(string)

Sets the response content type.

Inherited from IPageResponse.SetContentType.

Parameters

contentType
The media type to send.

MethodSetHeader(string, string)

Sets a response header the page is allowed to control.

Inherited from IPageResponse.SetHeader.

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.

Inherited from IPageResponse.AllowScripts.

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, int)

Exceptions

An embedded page cannot redirect.

MethodRedirectToLogin()

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

Inherited from IPageResponse.RedirectToLogin.

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.

Inherited from IPageResponse.AntiforgeryField.

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.

Pages.SqlitePageBatchStore

Writes an imported batch with one context and one transaction.

The commit is short — inserts only, no compilation — so the SQLite write lock is held for milliseconds rather than minutes. Every merged state total is checked before any row is written; if one page would exceed a cap the whole batch is refused and nothing changes.

Revisions go first because the head's foreign key points at them, then heads, then state. A crash during the commit is rolled back by SQLite, and a failed write rolls back explicitly, so a reader sees the old pages until the commit and the whole new set after it.

MethodSqlitePageBatchStore(Storage.StorageDbContext, Pages.PageStorageOptions, TimeProvider, ILogger<Pages.SqlitePageBatchStore>, Storage.PageStorageRefresh)

Writes an imported batch with one context and one transaction.

The commit is short — inserts only, no compilation — so the SQLite write lock is held for milliseconds rather than minutes. Every merged state total is checked before any row is written; if one page would exceed a cap the whole batch is refused and nothing changes.

Revisions go first because the head's foreign key points at them, then heads, then state. A crash during the commit is rolled back by SQLite, and a failed write rolls back explicitly, so a reader sees the old pages until the commit and the whole new set after it.

MethodSaveBatchAsync(IReadOnlyList<Pages.PageBatchSave>, CancellationToken)

Stores every page in one transaction.

Inherited from Pages.IPageBatchStore.SaveBatchAsync.

Parameters

pages
The pages to store, in key order.
cancellationToken
Cancels the write.

Returns

Committed, or the pages whose merged state would overflow a cap. A refusal writes nothing.

MethodWriteStateAsync(Storage.StorageDbContext database, PagePath path, Pages.PageStateValue value, DateTimeOffset updatedAt, CancellationToken cancellationToken)

Writes one state row, under every per-page cap.
Virtual so a fixture can fail one page's write and prove the whole batch rolls back; the production path is the same statement a page's own write uses.

Parameters

database
The context the batch transaction runs in.
path
The page whose state is written.
value
The value to write.
updatedAt
The row's timestamp.
cancellationToken
Cancels the write.

Returns

1 when the row was written, 0 when a cap refused it.

Pages.SqlitePageReadStore

The EF Core implementation of a page's read-only view of the store.

Every call creates and disposes its own Storage.StorageDbContext, for Pages.SqlitePageStateStore's reason: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed context.

The seam is read-only by construction: there is no SaveChangesAsync call site, no transaction, and nothing that names a Pages.PageImage or its builder.

MethodSqlitePageReadStore(IDbContextFactory<Storage.StorageDbContext>)

The EF Core implementation of a page's read-only view of the store.

Every call creates and disposes its own Storage.StorageDbContext, for Pages.SqlitePageStateStore's reason: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed context.

The seam is read-only by construction: there is no SaveChangesAsync call site, no transaction, and nothing that names a Pages.PageImage or its builder.

MethodListLibrariesAsync(CancellationToken)

Lists the live library pages, ordered by key.

Inherited from Pages.IPageReadStore.ListLibrariesAsync.

This is the compiler's read, not a page's: a library is an input to every page that names it, so a row cap here would stop those pages compiling rather than shorten a listing.

Parameters

cancellationToken
Cancels the read.

Returns

Every live library head, in ordinal key order.

MethodListAsync(string, int, CancellationToken)

Lists the heads under a prefix, ordered by key.

Inherited from Pages.IPageReadStore.ListAsync.

Parameters

prefix
The canonical subtree prefix; / is the whole store.
limit
The most rows to select, as a limit in the statement.
cancellationToken
Cancels the read.

Returns

At most limit heads, in ordinal key order.

MethodGetHeadAsync(string, CancellationToken)

Reads one head, which is how a caller learns what a key holds.

Inherited from Pages.IPageReadStore.GetHeadAsync.

It is one row rather than a listing of the key's subtree: a caller that needs a page's kind before it can decide anything must not be given its children as a side effect.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The head, a tombstone's included, or null when no page has that key.

MethodGetSourceAsync(string, CancellationToken)

Reads a live page's template.

Inherited from Pages.IPageReadStore.GetSourceAsync.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The template, or null when no live page has that key.

MethodListRevisionsAsync(string, CancellationToken)

Lists one page's history, newest first.

Inherited from Pages.IPageReadStore.ListRevisionsAsync.

Parameters

key
The canonical key to read.
cancellationToken
Cancels the read.

Returns

The page's revisions, including those of a tombstone; empty for an unknown key.

MethodGetRevisionSourceAsync(string, string, CancellationToken)

Reads one revision's template, by both of its handles.

Inherited from Pages.IPageReadStore.GetRevisionSourceAsync.

Parameters

key
The canonical key the revision belongs to.
hash
The revision's hash.
cancellationToken
Cancels the read.

Returns

The template, or null when that page has no such revision.

Pages.SqlitePageRevisionStore

The Pages.IPageRevisionStore over a context factory.
One context per save, created and disposed here. It calls the same StoreRevisionAsync the editor's save and an imported batch call, so a page's save is one more caller of the one insert rather than a second writer (`pages-a-page-may-save-itself`).

MethodSqlitePageRevisionStore(IDbContextFactory<Storage.StorageDbContext>, ILogger<Pages.SqlitePageRevisionStore>)

The Pages.IPageRevisionStore over a context factory.
One context per save, created and disposed here. It calls the same StoreRevisionAsync the editor's save and an imported batch call, so a page's save is one more caller of the one insert rather than a second writer (`pages-a-page-may-save-itself`).

MethodSaveAsync(Pages.PageTemplate, CancellationToken)

Inserts the revision and moves the page's head to it, in one transaction.

Inherited from Pages.IPageRevisionStore.SaveAsync.

Parameters

revision
The revision, already built with its id, hash and image.
cancellationToken
Cancels the write.

Returns

The revision that was stored. It is the argument unless another writer took its revision id, in which case it is the retry — so a caller that reports a hash reports the stored one.

MethodTrySaveAsync(Pages.PageTemplate, string, CancellationToken)

Inserts the revision and moves the head to it, only while the head still matches.

Inherited from Pages.IPageRevisionStore.TrySaveAsync.

Parameters

revision
The revision, already built with its id, hash and image.
expectedHash
The hash the caller saw as the head.
cancellationToken
Cancels the write.

Returns

false when the head is missing, tombstoned or another hash, so nothing was written.

Pages.SqlitePageSessionStore

The EF Core implementation of one visitor's bounded key/value store.
Every call creates and disposes its own Storage.StorageDbContext, as page state does: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed context.

MethodSqlitePageSessionStore(IDbContextFactory<Storage.StorageDbContext>, Pages.PageSessionOptions, TimeProvider)

The EF Core implementation of one visitor's bounded key/value store.
Every call creates and disposes its own Storage.StorageDbContext, as page state does: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed context.

MethodFindAsync(string, CancellationToken)

Finds a session row.

Inherited from Pages.IPageSessionStore.FindAsync.

Parameters

sessionId
The id from the visitor's cookie.
cancellationToken
Cancels the read.

Returns

The row, or null when the id names no live session.

MethodEnsureAsync(string, string, CancellationToken)

Mints a session row, evicting at the live-session cap when it has to.

Inherited from Pages.IPageSessionStore.EnsureAsync.

Parameters

sessionId
The id to mint.
account
The normalised account name, or null.
cancellationToken
Cancels the write.

Returns

Whether the row exists afterwards. A mint is refused only when the table is at its cap and nothing at all can be evicted.

MethodTouchAsync(string, CancellationToken)

Slides a session's idle timer.

Inherited from Pages.IPageSessionStore.TouchAsync.

Parameters

sessionId
The id that was touched.
cancellationToken
Cancels the write.

MethodDeleteAsync(string, CancellationToken)

Deletes a session and every value it holds.

Inherited from Pages.IPageSessionStore.DeleteAsync.

Parameters

sessionId
The id to delete.
cancellationToken
Cancels the write.

Returns

Whether a row was deleted.

MethodGetValueAsync(string, string, string, CancellationToken)

Reads one value.

Inherited from Pages.IPageSessionStore.GetValueAsync.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to read.
cancellationToken
Cancels the read.

Returns

The stored JSON, or null when the key is absent.

MethodSetValueAsync(string, string, string, string, Pages.PageSessionCaps, CancellationToken)

Writes one value, applying every per-session cap in the same statement.

Inherited from Pages.IPageSessionStore.SetValueAsync.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to write.
value
The value as JSON.
caps
The caps this visitor's session obeys.
cancellationToken
Cancels the write.

Exceptions

ArgumentException
A cap was hit, or the session no longer exists.

MethodDeleteValueAsync(string, string, string, CancellationToken)

Removes one value.

Inherited from Pages.IPageSessionStore.DeleteValueAsync.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key the value belongs to.
key
The key to remove.
cancellationToken
Cancels the write.

Returns

Whether the key existed.

MethodListKeysAsync(string, string, CancellationToken)

Lists one page's keys.

Inherited from Pages.IPageSessionStore.ListKeysAsync.

Parameters

sessionId
The visitor's session.
pagePath
The canonical page key whose keys are listed.
cancellationToken
Cancels the read.

Returns

The keys, in ordinal order.

MethodListAllKeysAsync(string, CancellationToken)

Lists every page and key a session holds.

Inherited from Pages.IPageSessionStore.ListAllKeysAsync.

Parameters

sessionId
The visitor's session.
cancellationToken
Cancels the read.

Returns

The pairs, ordered by page and then key.

MethodRemoveExpiredAsync(CancellationToken)

Removes expired sessions, and trims the table to its live-session cap when it is over.

Inherited from Pages.IPageSessionStore.RemoveExpiredAsync.

Parameters

cancellationToken
Cancels the sweep.

Returns

What the sweep removed, by kind.

MethodUpsertAsync(Storage.StorageDbContext, string, string, string, string, Pages.PageSessionCaps, CancellationToken)

Writes one value under every per-session cap, in one statement.

Returns

How many rows were written: 1 on success, 0 when a cap or a missing session refused it.

Pages.SqlitePageStateStore

The EF Core implementation of one page's key/value store.
Every call creates and disposes its own Storage.StorageDbContext: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed one.

MethodSqlitePageStateStore(IDbContextFactory<Storage.StorageDbContext>, Pages.PageStorageOptions, TimeProvider, Storage.PageStorageRefresh)

The EF Core implementation of one page's key/value store.
Every call creates and disposes its own Storage.StorageDbContext: a render that was abandoned can outlive the request scope, and a page's task must never touch a disposed one.

MethodGetValueAsync(PagePath, string, CancellationToken)

Reads one value.

Inherited from Pages.IPageStateStore.GetValueAsync.

Parameters

path
The page whose state is read.
key
The key to read.
cancellationToken
Cancels the read.

Returns

The stored JSON, or null when the key is absent.

MethodSetValueAsync(PagePath, string, string, CancellationToken)

Writes one value, applying every per-page cap in the same statement.

Inherited from Pages.IPageStateStore.SetValueAsync.

Parameters

path
The page whose state is written.
key
The key to write.
value
The value as JSON.
cancellationToken
Cancels the write.

Exceptions

ArgumentException
A cap was hit, or the page is no longer live.

MethodUpsertAsync(Storage.StorageDbContext database, PagePath path, string key, string value, DateTimeOffset updatedAt, Pages.PageStorageOptions options, CancellationToken cancellationToken)

Writes one value under every per-page cap, in one statement.
Both paths that write state — a page's own SetValueAsync and an import's batch — go through this statement, so the columns, the conflict target and the caps cannot drift.

Parameters

database
The context the write runs in, which may be inside a batch transaction.
path
The page whose state is written.
key
The key to write.
value
The value as JSON.
updatedAt
The row's timestamp.
options
The caps the statement enforces.
cancellationToken
Cancels the write.

Returns

How many rows were written: 1 on success, 0 when a cap or a missing live page refused it.

MethodDeleteValueAsync(PagePath, string, CancellationToken)

Removes one key.

Inherited from Pages.IPageStateStore.DeleteValueAsync.

Parameters

path
The page whose state is written.
key
The key to remove.
cancellationToken
Cancels the write.

Returns

Whether the key existed.

MethodListKeysAsync(PagePath, CancellationToken)

Lists a page's keys.

Inherited from Pages.IPageStateStore.ListKeysAsync.

Parameters

path
The page whose keys are listed.
cancellationToken
Cancels the read.

Returns

The keys, in ordinal order.

MethodGetValuesAsync(PagePath, CancellationToken)

Reads every key and value a page holds.

Inherited from Pages.IPageStateStore.GetValuesAsync.

Parameters

path
The page whose state is read.
cancellationToken
Cancels the read.

Returns

The values, in ordinal key order; empty when the page has no state.

Pages.SqlitePageStore

The SQLite-backed page store.

MethodSqlitePageStore(Storage.StorageDbContext, ILogger<Pages.SqlitePageStore>, Storage.PageStorageRefresh, string)

The SQLite-backed page store.

MethodStoreRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, ILogger logger, CancellationToken cancellationToken)

Stores one revision and its head, retrying a revision id another writer took.
The editor's save, an imported batch and a page saving its own source all end here, so the transaction, the row shape and the retry cannot drift apart (`pages-a-page-may-save-itself`). The single save passes the request's context; a page's save opens one of its own, because its task can outlive the request (`pages-the-store-is-read-through-one-seam`).

Parameters

database
The context to write through.
template
The revision to store.
logger
Where a retry is recorded.
cancellationToken
Cancels the write.

Returns

The revision that was stored, which is a retry when another writer took the id.

MethodWriteRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, CancellationToken cancellationToken)

Inserts one revision and points the page's head at it.
An editor save and an imported batch go through this pair, so the row shape and the head upsert cannot drift. The revision insert comes first: the head's foreign key points at it.

Parameters

database
The context to write through, which may be inside a caller's transaction.
template
The revision to store.
cancellationToken
Cancels the write.

MethodWriteHeadAsync(Storage.StorageDbContext database, Pages.PageTemplate template, CancellationToken cancellationToken)

Points a page's head at an already stored revision, clearing a tombstone.

Parameters

database
The context to write through.
template
The revision the head should point at.
cancellationToken
Cancels the write.

MethodRegenerateRevision(Pages.PageTemplate template)

Gives a batch a fresh revision id and hash after a collision.

Parameters

template
The revision that collided.

MethodTryStoreRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, string expectedHash, ILogger logger, CancellationToken cancellationToken)

Stores a revision only while the page's head still has the hash the caller saw.
The editor's conditional save, a page's own conditional save and the assistant all come through here, whether the context belongs to a request or to a singleton's save.

Parameters

database
The context to write through.
template
The revision to store.
expectedHash
The hash the caller saw as the head.
logger
Notes a retried revision id.
cancellationToken
Cancels the write.

Pages.StreamOptions

Bounds a response a page keeps writing after its first flush.

The render budget before the first flush is TimeoutSeconds; from the commit the question changes from "how long may this page run" to "is this stream still alive", and these are the two clocks that answer it. Every value comes from Pages:Stream.

The silence clock is what catches a stall and is re-armed by every flush; the ceiling is what stops a page that never stops producing. A stream that reaches either is truncated.

PropertySlots

Streams allowed to be open at once.
Separate from Slots because a stream is mostly waiting while a render is mostly CPU. A stream releases its render slot at the commit and holds one of these until it ends.

PropertySilenceSeconds

How long a stream may go without a flush before it is cut.
May be a fraction of a second, down to MinimumTimeoutSeconds.

PropertyMaxSeconds

The longest a stream may stay open, measured from its commit.

PropertySilence

The silence clock as a time span.

PropertyMax

The ceiling as a time span.

MethodFromConfiguration(IConfiguration configuration)

Reads Pages:Stream.

Parameters

configuration
The application configuration.

Exceptions

A value is missing or unusable.

MethodFromConfiguration(Configuration.ConfigurationReader reader)

Reads Pages:Stream into the caller's report.

Parameters

reader
A reader opened on Pages:Stream, which the caller completes.

Pages.ViewCredential

A run's view token, attachable to its site's origin and nowhere else.

The page's credential is bound to a page and applies to a host over HTTPS, or over plaintext to loopback, on any port. A view's is narrower on purpose: one exact origin, scheme and port included, because a token minted for 127.0.0.1:8080 has no business reaching 127.0.0.1:9090.

A class rather than a record, for the reason Pages.PageCredential is one: the generated ToString would print the secret, and this type finds its way into log scopes.

FieldHeaderName

The header a view's token travels in.

MethodViewCredential(Uri origin, string token)

A credential for one run's view of one origin.

Parameters

origin
The site's origin, from SiteOptions.
token
The run's secret, which never leaves this object.

PropertyOrigin

The one origin this credential may be sent to.

PropertyName

A name safe to log, which never contains the value.

Inherited from Pages.IOutboundCredential.Name.

PropertyHeader

The request header the value is sent in.

Inherited from Pages.IOutboundCredential.Header.

PropertyHeaderValue

The header value: the scheme and one space, then the secret.

Inherited from Pages.IOutboundCredential.HeaderValue.

MethodAppliesTo(Uri)

Scheme, host and port must all match; a path or query on the request does not matter.

MethodToString()

Names the credential and the origin it is for, never its value.

Returns

A line safe to log.

Shell

Shell.ShellCatalogue

The site's own routes, and the menus they appear in, in one table.

Four things read this list: the key set a page may not claim (Reserved), the record the assistant is given when it reads a shell file (Text), the menus the shell draws (Links) and the same links given to a page through ShellLinks. They were three hand-written copies — and the assistant's prompt a fourth — so the table is the only place a route is described.

A route is a key the site's own code answers. A page link is a key a stored page answers — Home, the editor and the manual — and it is in the table because it is in a menu, not because the shell answers it. The editor's key is configuration, so its entry names a token rather than a path.

PropertyEntries

Every entry, in the order a menu reads them when its numbers tie.

PropertyRoutes

Every route the site's own code answers, in table order.

PropertyReserved

The keys no page may claim, in table order.
The shell's links as values, the Site menu first and each section in its reading order.

Parameters

path
The request's path, which the sign-in link returns to.
query
The request's raw query, carried into the sign-in link.
editorPath
The editor's own key, which is configuration.
Whether a visitor with this identity may follow the link.
A link to a route that answers only a signed-in visitor is hidden from everyone else, and the sign-in link is the one thing an owner does not need.

Parameters

link
The link to test.
authenticated
Whether the visitor has signed in.
Whether the request path is the place this link leads to.
The sign-in link carries the way back as a query, so its current check is the path it leads to rather than the href it was given. The match is the link's own: a tool is current beneath its own key, and a view is current only at it.

Parameters

link
The link to test.
path
The canonical request path.

MethodText(PagePath path)

The record a read of this key returns.
No trailing line break: the description is the last line, so five lines really are five. A key the table does not describe still answers, with the one sentence that says so, because the assistant reads a key it was told is a shell file and a shape it did not expect is worse than a record that admits it knows nothing.

Parameters

path
A canonical key.

Shell.ShellEntry

Something the shell draws a link to: a route it answers, or a page the store holds.

MethodShellEntry(Shell.ShellMenu[] Menus)

Something the shell draws a link to: a route it answers, or a page the store holds.

Parameters

Menus
The menus it appears in, if any.

PropertyMenus

The menus it appears in, if any.

MethodHref(string editorPath)

The href the entry is linked by.

Parameters

editorPath
The editor's own key, which is configuration.

Shell.ShellMenu

One appearance of an entry in a menu.

MethodShellMenu(ShellSection Section, ShellAudience Audience, int Order, string Text, ShellMatch Match)

One appearance of an entry in a menu.

Parameters

Section
The menu it appears in.
Audience
Who may follow it, which is not the route's audience: the sign-in form answers anyone, and its link is for the visitor who has not signed in.
Order
Its place in that menu; the sections are numbered independently.
Text
What it says, which the menu renders as the link's text.
Match
How a request path marks it current.

PropertySection

The menu it appears in.

PropertyAudience

Who may follow it, which is not the route's audience: the sign-in form answers anyone, and its link is for the visitor who has not signed in.

PropertyOrder

Its place in that menu; the sections are numbered independently.

PropertyText

What it says, which the menu renders as the link's text.

PropertyMatch

How a request path marks it current.

Shell.ShellPage

A stored page a menu links to.

FieldHome

The site's home page, which is a page like any other.

FieldEditor

The editor, whose key is Pages:Editor:Key.

FieldHelp

The author manual.
A page the store holds, which a menu links to as if it were the shell's.

MethodShellPageLink(Shell.ShellPage Page, Shell.ShellMenu[] Menus)

A page the store holds, which a menu links to as if it were the shell's.

Parameters

Page
Which page, as a token, because the editor's key is configuration.
Menus
The menus it appears in.

PropertyPage

Which page, as a token, because the editor's key is configuration.

MethodHref(string)

The href the entry is linked by.

Inherited from Shell.ShellEntry.Href.

Parameters

editorPath
The editor's own key, which is configuration.

Shell.ShellRoute

A route the site's own code answers, and the record the assistant reads.

MethodShellRoute(string Key, string Methods, ShellAudience Audience, string Description, Shell.ShellMenu[] Menus)

A route the site's own code answers, and the record the assistant reads.

Parameters

Key
The canonical key the route owns.
Methods
The methods it answers, as the model should hear them.
Audience
Who may reach it.
Description
One line: what the route does.
Menus
The menus it appears in, if any.

PropertyKey

The canonical key the route owns.

PropertyMethods

The methods it answers, as the model should hear them.

PropertyAudience

Who may reach it.

PropertyDescription

One line: what the route does.

PropertyAccessNote

The sentence Access gives instead of the derived one, for a throttle or a gate.

PropertyAccess

Who may reach it, in the model's words; derived from the audience unless it says more.

MethodHref(string)

The href the entry is linked by.

Inherited from Shell.ShellEntry.Href.

Parameters

editorPath
The editor's own key, which is configuration.

Storage

Storage.PageStorageRefresh

Wakes the storage sampler after a write, coalescing repeated requests.

Storage.PageStorageSampler

Samples the database file's size and records it for the status page.

MethodPageStorageSampler(IServiceScopeFactory, Pages.PageMetrics, Storage.PageStorageRefresh, ILogger<Storage.PageStorageSampler>)

Samples the database file's size and records it for the status page.

Storage.SqliteCommandExtensions

Parameters for the stores' hand-written statements.
The conversation store and the memory store both run SQL themselves, and a timestamp has to be written the way every table stores one rather than left to the provider's default rendering.

MethodAddParameter(DbCommand command, string name, object value)

Adds a parameter, with a timestamp written as round-trip text.

Parameters

command
The command to add it to.
name
The parameter's name, sigil included.
value
The value to bind.

Storage.SqliteErrors

The SQLite failures a store treats as an ordinary race rather than a fault.

FieldRetryCount

How many times a write that may lose a race on a unique value is attempted.

MethodIsUniqueViolation(DbUpdateException exception)

Whether a failed update lost a race on a unique value, so a fresh value may succeed.

Parameters

exception
The failure a save threw.

Storage.StorageDbContext

The EF Core context: every table the site stores, mapped in one place.

MethodStorageDbContext(DbContextOptions<Storage.StorageDbContext>)

The EF Core context: every table the site stores, mapped in one place.

Storage.Migrations

Storage.Migrations.AddAssistantMemory

The assistant's memory: two ordinary tables, an index, and an FTS5 index over the heads.
EF Core cannot model a virtual table, so the FTS5 table and its three triggers are raw SQL in the same migration and the model snapshot does not mention them. That is also why Down drops them by hand: the generated reversal only knows the two tables. The DDL is the text the spike ran and checked with FTS5's own integrity-check.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddOwnerInterrupts

One record for every time a run waits on its owner: approvals and budget continuations move from their two shapes into AssistantInterrupts, the two waiting statuses become one, and the paused budget moves from a column into the continuation's stored request.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageHeadSeedProvenance

Gives a page's head the two content hashes seed provenance needs.
Both are nullable and null for every row that exists: the anchor cannot be recovered, and the content hash is filled by the startup repair. A null anchor is unknown, never "unchanged", so no existing page becomes eligible for an automatic seed write.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageRevisionTemplateHasCode

Adds the verdict that says a revision has nothing to compile.
Nullable on purpose: an existing revision has never been judged and stays that way until something generates it again. There is no backfill pass.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageRevisionTemplateKind

Turns the has-code verdict into the kind of page a revision is.

The column is renamed rather than copied, because the two answers are ordered the same way: a stored 0 meant "no code" and is Text, a stored 1 meant "has code" and is Page, and NULL still means never judged. No row can hold Library yet.

Nullable on purpose, as it was: a revision nobody has generated stays unjudged until something generates it again, and there is no backfill pass.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageRevisionTemplateLibraries

Adds the fingerprint of the libraries an image was compiled against.
Nullable, and null for every row that exists: a page that names no library has no closure, and a page compiled before libraries existed is stale on its next request anyway. The value is opaque — a sorted key@revisionHash per library — and is compared with the live heads, never read as data.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageSessions

A visitor's session, and the values pages keep in it.
PageSessions carries the sliding timestamp and the account, and PageSessionValues holds one row per value keyed by session, page and key, cascading from the session row. Two indexes back the sweep and the eviction order: one on the account and timestamp, one on the timestamp alone.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddPageState

Inherited from Migration.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddRunContinuation

A run that runs out of a budget waits for the owner instead of failing.
The three columns say which budget ran out and what the run's budgets have grown to, and the active-run index grows the new status so a paused run still owns its conversation.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddRunEstimate

Keeps the last request's estimate and reply allowance with the run.
The estimate is what the panel's signed error row is measured from, and the allowance is the ceiling the completion row is read against. Both are null for every row that exists, which is right: a run written before this change recorded neither.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.AddRunUsage

Inherited from Migration.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Storage.Migrations.InitialCreate

Inherited from Migration.

MethodUp(MigrationBuilder)

Inherited from Migration.Up.

MethodDown(MigrationBuilder)

Inherited from Migration.Down.

MethodBuildTargetModel(ModelBuilder)

Inherited from Migration.BuildTargetModel.

Users

Users.IPasswordService

Hashes passwords and checks a candidate against a stored hash.

MethodHash(Users.LocalUser user, string password)

Hashes a password for an account.

Parameters

user
The account the hash belongs to.
password
The plaintext password.

MethodVerify(Users.LocalUser user, string password)

Checks a candidate password against the account's stored hash.

Parameters

user
The account to check.
password
The candidate password.

Returns

PasswordVerificationResult.Failed for a wrong password or a malformed hash; otherwise the hasher's result. Callers rehash on PasswordVerificationResult.SuccessRehashNeeded.

MethodVerifyDummy(string password)

Runs a verification even though the account is unknown, then reports failure.

Parameters

password
The candidate password.

Returns

Always false; the point is the time spent hashing.

Users.IUserConsole

The console operations the user command needs, so its logic can be tested.

MethodReadPassword(string)

Writes a prompt and reads a password without echoing it.

MethodWriteLine(string)

Writes an informational line.

MethodWriteError(string)

Writes an error line.

Users.IUserStore

Stores the local accounts the CLI manages.
Every user name passed to this store is already normalised by Normalize.

MethodFindAsync(string userName, CancellationToken cancellationToken)

Finds an account by its normalised name.

Parameters

userName
The normalised name.
cancellationToken
Cancels the read.

MethodTryAddAsync(Users.LocalUser user, CancellationToken cancellationToken)

Adds an account unless the name is already taken.

Parameters

user
The account to add.
cancellationToken
Cancels the write.

Returns

true when the account was added.

MethodUpdateHashAsync(string userName, string passwordHash, CancellationToken cancellationToken)

Replaces the hash without touching the security stamp.

Parameters

userName
The normalised name.
passwordHash
The new hash.
cancellationToken
Cancels the write.

Returns

true when the account existed.

MethodChangePasswordAsync(string userName, string passwordHash, string securityStamp, CancellationToken cancellationToken)

Replaces the hash and the security stamp, revoking existing cookies.

Parameters

userName
The normalised name.
passwordHash
The new hash.
securityStamp
The new stamp.
cancellationToken
Cancels the write.

Returns

true when the account existed.

MethodListAsync(CancellationToken cancellationToken)

Lists accounts in name order.

Parameters

cancellationToken
Cancels the read.

MethodRemoveAsync(string userName, CancellationToken cancellationToken)

Removes an account.

Parameters

userName
The normalised name.
cancellationToken
Cancels the write.

Returns

true when the account existed.

Users.LocalUser

A local account that may sign in to the editor.
The user name is already normalised by Normalize; the password is stored only as a hash produced by Users.IPasswordService. The security stamp is rotated when the password changes, so existing long-term cookies stop validating.

PropertyUserName

The normalised user name, which is the primary key.

PropertyPasswordHash

The password hash.

PropertySecurityStamp

The revocation stamp carried in an authentication cookie.

PropertyCreatedAt

When the account was created.

Users.PasswordPolicy

The rule applied when a password is set.

FieldMinimumLength

The shortest accepted password.

FieldMaximumLength

The longest accepted password, so a login cannot spend unbounded time hashing.

MethodValidate(string password)

Validates a candidate password.

Parameters

password
The password to test.

Exceptions

ArgumentException
The password is outside the accepted length.

Users.PasswordService

The PBKDF2 password hasher shared by the login endpoint and the CLI.

MethodHash(Users.LocalUser, string)

Hashes a password for an account.

Inherited from Users.IPasswordService.Hash.

Parameters

user
The account the hash belongs to.
password
The plaintext password.

MethodVerify(Users.LocalUser, string)

Checks a candidate password against the account's stored hash.

Inherited from Users.IPasswordService.Verify.

Parameters

user
The account to check.
password
The candidate password.

Returns

PasswordVerificationResult.Failed for a wrong password or a malformed hash; otherwise the hasher's result. Callers rehash on PasswordVerificationResult.SuccessRehashNeeded.

MethodVerifyDummy(string)

Runs a verification even though the account is unknown, then reports failure.

Inherited from Users.IPasswordService.VerifyDummy.

Parameters

password
The candidate password.

Returns

Always false; the point is the time spent hashing.

Users.SecurityStamp

Creates the value that revokes authentication cookies when an account changes.

MethodCreate()

Creates a new random stamp.

Users.SqliteUserStore

The SQLite-backed account store.

MethodSqliteUserStore(Storage.StorageDbContext, ILogger<Users.SqliteUserStore>)

The SQLite-backed account store.

MethodFindAsync(string, CancellationToken)

Finds an account by its normalised name.

Inherited from Users.IUserStore.FindAsync.

Parameters

userName
The normalised name.
cancellationToken
Cancels the read.

MethodTryAddAsync(Users.LocalUser, CancellationToken)

Adds an account unless the name is already taken.

Inherited from Users.IUserStore.TryAddAsync.

Parameters

user
The account to add.
cancellationToken
Cancels the write.

Returns

true when the account was added.

MethodUpdateHashAsync(string, string, CancellationToken)

Replaces the hash without touching the security stamp.

Inherited from Users.IUserStore.UpdateHashAsync.

Parameters

userName
The normalised name.
passwordHash
The new hash.
cancellationToken
Cancels the write.

Returns

true when the account existed.

MethodChangePasswordAsync(string, string, string, CancellationToken)

Replaces the hash and the security stamp, revoking existing cookies.

Inherited from Users.IUserStore.ChangePasswordAsync.

Parameters

userName
The normalised name.
passwordHash
The new hash.
securityStamp
The new stamp.
cancellationToken
Cancels the write.

Returns

true when the account existed.

MethodListAsync(CancellationToken)

Lists accounts in name order.

Inherited from Users.IUserStore.ListAsync.

Parameters

cancellationToken
Cancels the read.

MethodRemoveAsync(string, CancellationToken)

Removes an account.

Inherited from Users.IUserStore.RemoveAsync.

Parameters

userName
The normalised name.
cancellationToken
Cancels the write.

Returns

true when the account existed.

Users.SystemUserConsole

The real console, including a password prompt that does not echo.

MethodReadPassword(string)

Writes a prompt and reads a password without echoing it.

Inherited from Users.IUserConsole.ReadPassword.

MethodWriteLine(string)

Writes an informational line.

Inherited from Users.IUserConsole.WriteLine.

MethodWriteError(string)

Writes an error line.

Inherited from Users.IUserConsole.WriteError.

Users.UserCommands

The account command that runs before the web host starts.

FieldName

The command word that selects the account tool.

MethodIsCommand(string[] args)

Whether the process arguments are an account command.

Parameters

args
The process arguments.

MethodRunAsync(string[] args, IServiceProvider services, CancellationToken cancellationToken)

Runs an account command against the application's services.

Parameters

args
The arguments after users.
services
The application's service provider.
cancellationToken
Cancels the command.

Returns

The process exit code.

Users.UserName

The pure rule for the key an account is stored under.

FieldMaximumLength

The longest accepted user name, after normalisation.

MethodNormalize(string userName)

Trims, lowercases, NFC-normalises and validates a user name.

Parameters

userName
The text submitted by a login form or the CLI.

Returns

The normalised key, in Unicode NFC.

Exceptions

ArgumentException
The text is empty, too long or contains control characters.

Work

Work.BoundedWorkQueue<T>

A bounded queue of background work, with a slot taken before the work is queued.
A reservation is taken before the work is written, so a queue that is full refuses the request rather than growing without bound, and the read that starts the work is what releases the slot. The channel's own bound is the same number, so it is a backstop rather than the limit.

Type parameters

T
The work item.

MethodBoundedWorkQueue(int)

A bounded queue of background work, with a slot taken before the work is queued.
A reservation is taken before the work is written, so a queue that is full refuses the request rather than growing without bound, and the read that starts the work is what releases the slot. The channel's own bound is the same number, so it is a backstop rather than the limit.

Type parameters

T
The work item.

MethodTryReserve()

Takes one of the queue's slots.

Returns

false when every slot is taken.

MethodReleaseReservation()

Returns a reservation that was not used.

MethodTryEnqueueReserved(T item)

Queues work whose reservation is already held.

Parameters

item
The work to queue.

Returns

false when the channel would not accept it.

MethodTryEnqueue(T item)

Reserves a slot and queues work.

Parameters

item
The work to queue.

Returns

false when the queue is full.

MethodReadAllAsync(CancellationToken cancellationToken)

Reads queued work until the host stops, releasing each slot as its work starts.

Parameters

cancellationToken
Cancels the read.

Work.IWorkerStore

The page store as a job reads it: one worker, and the image it was compiled to.
It exists because a job outlives the request that started it while Pages.IPageStore is scoped to one, so the singleton that runs jobs cannot hold it. Every call owns its scope, the way the page store's read seam does.

MethodGetAsync(PagePath worker, CancellationToken cancellationToken)

Reads the worker stored at a key.

Parameters

worker
The worker's canonical key.
cancellationToken
Cancels the read.

Returns

The revision the head points at, or null when nothing is stored there.

MethodTrySetImageAsync(string revisionId, string template, Pages.PageImage image, CancellationToken cancellationToken)

Stores a rebuilt worker's image against the revision it was built from.

Parameters

revisionId
The revision the image belongs to.
template
The template it was built from.
image
The image to store.
cancellationToken
Cancels the write.

Returns

Whether the revision still had that template, so the write was kept.

Work.JobEnd

Why a job's deadline was reached, when it was not the worker returning.

FieldCompleted

The worker returned on its own.

FieldCancelled

A page, or the host stopping, asked for it to end.

FieldSilence

It published and received nothing for Pages:Jobs:SilenceSeconds.

FieldCeiling

It ran for Pages:Jobs:MaxDurationSeconds.

Work.JobLifetime

The two clocks a job runs against, and how it ended.

The silence clock is what notices a stall and is re-armed by everything the worker does; the ceiling is what ends work that never stops. A wait in ReceiveAsync is not silence — a worker waiting on its owner is doing as it was told — so a wait pauses the silence clock and only the ceiling bounds it.

The reason is recorded before the token is cancelled, so whichever await the worker unwinds at can still say which clock ended it.

MethodJobLifetime(Pages.PageJobOptions options)

Starts the clocks.

Parameters

options
The job's bounds.

PropertyEnd

What ended the job, or Completed while it is still running.

PropertyToken

The token a worker waits against.

MethodReArm()

Restarts the silence clock, after a publish or a returned receive.

MethodPause()

Stops the silence clock, because the worker is waiting for its owner.
The ceiling keeps running: a wait is bounded by how long the job may live, not by how quiet it is allowed to be, so an indefinite wait still ends at MaxDurationSeconds.

MethodResume()

Restarts the silence clock after a wait.

MethodCancel()

Ends the job because somebody asked it to stop.

MethodDispose()

Inherited from IDisposable.Dispose.

Work.PageJob

One job in memory: its identity, its owner, its messages and its journal.
A job does not survive a restart, so nothing here is stored: the starting page's own state is the record, and a page that finds its state says running while GetAsync answers nothing knows the host restarted. The record is kept after the job ends until it is swept, so a viewer that reloads can still read what the job published.

MethodPageJob(string id, PagePath worker, PagePath page, PageUser owner, string input, Pages.PageJobOptions options, TimeProvider clock)

Creates a job that is waiting for a runner.

Parameters

id
The job's id.
worker
The worker's canonical key.
page
The starting page's canonical key.
owner
The visitor the job runs for.
input
The first message, or null when there was none.
options
The job's bounds.
clock
Where the times come from.

PropertyId

The job's id.

PropertyWorker

The worker's canonical key.

PropertyPage

The starting page's canonical key.

PropertyOwner

The visitor the job runs for.

PropertyInput

The first message, or null.

PropertyStartedAt

When the job was accepted.

PropertyJournal

The events the worker has published.

PropertyLifetime

The job's own clocks.

MethodSnapshot()

Reads the job as its owner sees it.

MethodMarkRunning()

Marks the job as running, once a runner has it.

MethodTrySend(string message)

Queues one message for the worker.

Parameters

message
The message.

Returns

None when it was queued, or why it was not.

MethodReceiveAsync(TimeSpan? wait, CancellationToken aborted)

Waits for the next message.
The wait pauses the silence clock: a worker waiting for its owner has not gone quiet, and the ceiling is what bounds it.

Parameters

wait
How long to wait, or null to wait until the job ends.
aborted
Cancels the wait when the job must stop.

Returns

The message, or null when the wait elapsed or the job ended.

MethodEnd(PageJobState state, string failure)

Ends the job and wakes everyone waiting on it.

Parameters

state
How it ended.
failure
Why it failed, or null when it did not.

MethodDispose()

Inherited from IDisposable.Dispose.

Work.PageJobJournal

One job's published events: a bounded ring a viewer can replay, and wait on.

Events are progress, not a record: the ring keeps the most recent ones and drops the oldest past MaxEvents, MaxEventBytes or RetentionMinutes, because a worker that runs for a working day publishes more than any page could read. What must survive belongs in the starting page's storage.

A viewer that asks for a sequence the ring no longer holds is told so rather than quietly handed a gap, and a wait is answered by a signal the publisher swaps under the lock, so an event published while a viewer is arming is not missed.

MethodPageJobJournal(Pages.PageJobOptions, TimeProvider)

One job's published events: a bounded ring a viewer can replay, and wait on.

Events are progress, not a record: the ring keeps the most recent ones and drops the oldest past MaxEvents, MaxEventBytes or RetentionMinutes, because a worker that runs for a working day publishes more than any page could read. What must survive belongs in the starting page's storage.

A viewer that asks for a sequence the ring no longer holds is told so rather than quietly handed a gap, and a wait is answered by a signal the publisher swaps under the lock, so an event published while a viewer is arming is not missed.

MethodPublish(string type, string dataJson)

Publishes one event, dropping it when it is larger than the journal allows.

Parameters

type
What the event is.
dataJson
Its text or JSON.

Returns

false when the event was too large to keep and was dropped.

MethodSignalEnd()

Wakes every waiter, because the job ended and no more events are coming.

MethodWaitAsync(TimeSpan wait, CancellationToken cancellationToken)

Waits until an event is published or the job ends.

Parameters

wait
How long to wait.
cancellationToken
Cancels the wait.

Returns

A task that completes when there is something new to read.

MethodRead(long after)

Reads every event after a sequence.

Parameters

after
The last sequence the caller has seen; 0 reads from the start.

Work.PageJobJournal.Snapshot

What one read of the ring answered.

MethodSnapshot(IReadOnlyList<PageJobEvent> Events, long Next, bool Reset)

What one read of the ring answered.

Parameters

Events
The events after the caller's sequence.
Next
The sequence to pass back next.
Reset
Whether the caller's sequence had been dropped.

PropertyEvents

The events after the caller's sequence.

PropertyNext

The sequence to pass back next.

PropertyReset

Whether the caller's sequence had been dropped.

Work.PageJobQueue

The queue a start is written to and the runner reads.

MethodPageJobQueue(Pages.PageJobOptions)

The queue a start is written to and the runner reads.

Work.PageJobRequest

One job waiting for a runner.

MethodPageJobRequest(string Id, PagePath Worker, PagePath Page, PageUser Owner)

One job waiting for a runner.

Parameters

Id
The job's id, which is also how the registry finds it.
Worker
The worker's canonical key.
Page
The starting page's canonical key.
Owner
The visitor the job runs for.

PropertyId

The job's id, which is also how the registry finds it.

PropertyWorker

The worker's canonical key.

PropertyPage

The starting page's canonical key.

PropertyOwner

The visitor the job runs for.

Work.PageJobRunner

Runs queued jobs, a bounded number at a time, each with its own scope and load context.

A job takes a job slot rather than a render slot, because it is not answering a visitor: the runner keeps Pages:Jobs:MaxConcurrent of them going and the queue's own bound is what refuses the next start. Each job gets a scope of its own, so the page store it reads is its own, and the worker's assembly is unloaded when its job ends.

The worker's image is loaded the way a page's is: the stored image is used when it is current, and rebuilt when the build changed or a library it named has moved. A worker that no longer compiles, or is no longer stored as one, is a failed job with the reason, never a silent one.

MethodPageJobRunner(Work.PageJobQueue, Work.PageJobs, Pages.PageJobEnvironment, ILoggerFactory, ILogger<Work.PageJobRunner>)

Runs queued jobs, a bounded number at a time, each with its own scope and load context.

A job takes a job slot rather than a render slot, because it is not answering a visitor: the runner keeps Pages:Jobs:MaxConcurrent of them going and the queue's own bound is what refuses the next start. Each job gets a scope of its own, so the page store it reads is its own, and the worker's assembly is unloaded when its job ends.

The worker's image is loaded the way a page's is: the stored image is used when it is current, and rebuilt when the build changed or a library it named has moved. A worker that no longer compiles, or is no longer stored as one, is a failed job with the reason, never a silent one.

MethodDispose()

Inherited from BackgroundService.Dispose.

MethodExecuteAsync(CancellationToken)

Inherited from BackgroundService.ExecuteAsync.

Work.PageJobs

The host's jobs: what a page starts, and what a viewer reads.

The registry is in memory and the queue is the existing bounded one, so a start is refused rather than queued without bound, and a restart loses every job — a worker that is given the transcript writes each step to the starting page's storage, which is the record, and the page that finds its own state says running while Get answers nothing knows the host restarted.

Nothing here takes an owner argument from page code: every call is filtered against the visitor the capability was bound to, so a page cannot read, talk to or stop another visitor's job. Every refusal is a value, and every refusal is logged with the page that asked.

MethodPageJobs(Pages.PageJobOptions, Work.PageJobQueue, Pages.ReservedPaths, Pages.IPageReadStore, TimeProvider, ILogger<Work.PageJobs>)

The host's jobs: what a page starts, and what a viewer reads.

The registry is in memory and the queue is the existing bounded one, so a start is refused rather than queued without bound, and a restart loses every job — a worker that is given the transcript writes each step to the starting page's storage, which is the record, and the page that finds its own state says running while Get answers nothing knows the host restarted.

Nothing here takes an owner argument from page code: every call is filtered against the visitor the capability was bound to, so a page cannot read, talk to or stop another visitor's job. Every refusal is a value, and every refusal is logged with the page that asked.

PropertyOptions

The bounds a caller's waits and messages are held to.

MethodStartAsync(PagePath page, string workerKey, string firstMessage, PageUser owner, CancellationToken cancellationToken)

Starts one run of a stored worker.

Parameters

page
The page asking, for the log line and for the job's own storage.
workerKey
The worker's key, as the page spelled it.
firstMessage
The first message, or null.
owner
The signed-in visitor, or null when the render is anonymous.
cancellationToken
Bounds the kind check, which is the only I/O here.

MethodSend(PagePath page, string jobId, string message, PageUser owner)

Queues one message for a job this visitor owns.

Parameters

page
The page asking, for the log line.
jobId
The job's id.
message
The message.
owner
The signed-in visitor.

MethodGet(string jobId, PageUser owner)

Reads one job this visitor owns.

Parameters

jobId
The job's id.
owner
The signed-in visitor.

MethodList(PageUser owner)

Lists this visitor's jobs, in the order they were started.

Parameters

owner
The signed-in visitor.

MethodReadEventsAsync(string jobId, long after, TimeSpan wait, PageUser owner, CancellationToken cancellationToken)

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

Parameters

jobId
The job's id.
after
The last sequence the caller has seen.
wait
How long to wait for something new.
owner
The signed-in visitor.
cancellationToken
Ends the wait when the render does.

MethodCancel(PagePath page, string jobId, PageUser owner)

Asks a job to stop.

Parameters

page
The page asking, for the log line.
jobId
The job's id.
owner
The signed-in visitor.

Returns

Whether a running job was asked; a finished or unknown one answers false.

MethodFind(string jobId)

Finds one job by id, whoever owns it.

Parameters

jobId
The job's id.

Returns

The job, or null when no job has that id.

Work.ScopedWorkerStore

One scope per call, because a job's own scope may be doing something else.

MethodScopedWorkerStore(IServiceScopeFactory)

One scope per call, because a job's own scope may be doing something else.

MethodGetAsync(PagePath, CancellationToken)

Reads the worker stored at a key.

Inherited from Work.IWorkerStore.GetAsync.

Parameters

worker
The worker's canonical key.
cancellationToken
Cancels the read.

Returns

The revision the head points at, or null when nothing is stored there.

MethodTrySetImageAsync(string, string, Pages.PageImage, CancellationToken)

Stores a rebuilt worker's image against the revision it was built from.

Inherited from Work.IWorkerStore.TrySetImageAsync.

Parameters

revisionId
The revision the image belongs to.
template
The template it was built from.
image
The image to store.
cancellationToken
Cancels the write.

Returns

Whether the revision still had that template, so the write was kept.

Work.WorkerContext

One job's IWorkerContext: its identity, its capabilities and its channel.
It has no response members at all, because a job answers nobody. Its log entries are filed under the page category with the job's own scope, so a worker's line is found beside the render that started it.

MethodWorkerContext(Work.PageJob, Pages.PageCapabilities, Pages.PageJobOptions, ILogger)

One job's IWorkerContext: its identity, its capabilities and its channel.
It has no response members at all, because a job answers nobody. Its log entries are filed under the page category with the job's own scope, so a worker's line is found beside the render that started it.

PropertyId

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

Inherited from IWorkerContext.Id.

PropertyPath

The canonical key of the page that started the job.

Inherited from IWorkerContext.Path.

PropertyWorker

The canonical key of the worker source that is running.

Inherited from IWorkerContext.Worker.

PropertyUser

The visitor the job runs for.

Inherited from IWorkerContext.User.

PropertyInput

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

Inherited from IWorkerContext.Input.

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.

Inherited from IWorkerContext.Aborted.

PropertyCapabilities

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

Inherited from IWorkerContext.Capabilities.

MethodLog(string)

Writes to the job's log.

Inherited from IWorkerContext.Log.

Parameters

message
The message.

MethodLogWarning(string)

Writes a warning to the job's log.

Inherited from IWorkerContext.LogWarning.

Parameters

message
The message.

MethodLogError(string)

Writes an error to the job's log.

Inherited from IWorkerContext.LogError.

Parameters

message
The message.

MethodReceiveAsync(double?)

Waits for the next message sent to this job.

Inherited from IWorkerContext.ReceiveAsync.

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, string)

Publishes one event to this job's journal.

Inherited from IWorkerContext.Publish.

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.