The site
uk.osric.asp.Web
Program
SiteOptions
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
PropertyOrigin
MethodTryResolve(string path, ref string url, ref string problem)
// 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)
Site.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Site into the caller's report.Parameters
reader- A reader opened on
Site, which the caller completes.
Admin
Admin.AdminIndexEndpoint
MethodHandleAsync(HttpContext context, CancellationToken cancellationToken)
GET /admin.Parameters
context- The response being written.
cancellationToken- Aborted when the request is abandoned.
Admin.AdminNavigation
FieldLabel
MethodNav(HttpContext context)
Parameters
context- The request being answered, whose path marks the current tool.
Admin.AdminOptions
PropertyChangelist
MethodFromConfiguration(IConfiguration configuration)
Admin.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Admin into the caller's report.Parameters
reader- A reader opened on
Admin, which the caller completes.
Admin.AdminPage
FieldBackLinks
MethodBeginAsync(HttpContext context, string title)
Parameters
context- The request being answered.
title- The document's title, escaped on the way out.
MethodEndAsync(HttpContext context)
Parameters
context- The request being answered.
Returns
Admin.ApplySeedsEndpoint
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)
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)
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
PRAGMA table_info describes it.MethodArchiveColumn(string Name, bool NotNull, int PrimaryKey)
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
PropertyNotNull
NOT NULL.PropertyPrimaryKey
Admin.ArchiveOptions
Pages:Archive.
PropertyMaxUploadBytes
PropertyMaxPages
PropertyMaxCompiledBytes
PropertyStageTtlMinutes
PropertyMaxStagedImports
PropertyStageTtl
MethodFromConfiguration(IConfiguration configuration)
Pages:Archive.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Archive into the caller's report.Parameters
reader- A reader opened on
Pages:Archive, which the caller completes.
Admin.ChangesEndpoint
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
MethodHandleAsync(HttpContext context, Admin.AdminOptions options)
Parameters
context- The request being answered.
options- Names the file, from
Admin:Changelist.
MethodReadAsync(Admin.AdminOptions, CancellationToken)
null when this build carries none.MethodPathOf(Admin.AdminOptions)
MethodParse(string)
Admin.ChangesEndpoint.Commit
MethodCommit(string, string)
Admin.CopyrightEndpoint
/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)
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
MethodListAsync(HttpContext context, Pages.IPageStore pages, Pages.ReservedPaths reserved, Pages.PageSeeds seeds, IAntiforgery antiforgery)
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)
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
FieldReviewing
FieldQueued
FieldCompiling
FieldSaving
FieldCommitted
FieldFailed
Admin.ImportEndpoint
FieldFormOverheadBytes
FieldArchiveField
FieldIncludeField
MethodUploadFormAsync(HttpContext context, IAntiforgery antiforgery, Admin.ArchiveOptions options)
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)
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)
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)
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)
Parameters
context- The request being answered.
stages- The staged archives.
Admin.ImportPageResult
MethodImportPageResult(PagePath Path, Admin.ImportPageStatus Status, IReadOnlyList<PageDiagnostic> Diagnostics)
Parameters
Path- The page being imported.
Status- How far it got.
Diagnostics- The compiler's diagnostics, when it did not compile cleanly.
PropertyPath
PropertyStatus
PropertyDiagnostics
Admin.ImportPageStatus
FieldWaiting
FieldStoredAsSource
FieldCompiled
FieldCompiledWithWarnings
FieldCompiledWithErrors
FieldCompilerFault
FieldLibrary
FieldLibraryWithIssues
Admin.ImportProcessor
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>)
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)
Parameters
stage- The stage holding the archive and its results.
cancellationToken- Cancels the batch.
Admin.ImportQueue
MethodImportQueue(Admin.ArchiveOptions options)
Parameters
options- The archive options, whose staged-import count bounds the queue.
Admin.ImportStage
MethodImportStage(string id, IReadOnlyList<Admin.PageArchiveEntry> pages, DateTimeOffset createdAt)
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
PropertyPages
PropertyCreatedAt
PropertyIsRunning
MethodFind(PagePath path)
Parameters
path- The canonical key.
MethodTryApprove(IReadOnlyList<PagePath> selected)
Parameters
selected- The pages the approval ticked, in key order.
Returns
false when this stage is already importing.MethodUnqueue()
MethodBeginCompiling()
MethodBeginSaving()
MethodRecord(Admin.ImportPageResult result)
Parameters
result- The result to record.
MethodCommit(string message)
Parameters
message- A sentence for the reader.
MethodFail(string message, IReadOnlyList<PagePath> refused)
Parameters
message- A sentence naming the reason.
refused- The pages whose merged state would not fit, when that is the reason.
MethodSnapshot()
Admin.ImportStageSnapshot
MethodImportStageSnapshot(Admin.ImportBatchStatus Status, IReadOnlyList<PagePath> Selected, IReadOnlyList<Admin.ImportPageResult> Results, IReadOnlyList<PagePath> Refused, string Message)
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
PropertySelected
PropertyResults
PropertyRefused
PropertyMessage
Admin.ImportStageStore
MethodImportStageStore(Admin.ArchiveOptions, TimeProvider)
FieldIdLength
PropertyCount
MethodCreate(IReadOnlyList<Admin.PageArchiveEntry> pages)
Parameters
pages- The validated pages.
Returns
MethodGet(string id)
Parameters
id- The identifier from the URL.
Returns
null when it is unknown, malformed or expired.MethodIsWellFormed(string id)
404 for anything a stage could never be named.
Parameters
id- The text from the URL.
Admin.ImportWorker
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>)
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 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)
Parameters
directory- The directory the build copied them into, normally the assembly's own.
PropertySiteLicence
LICENSE), or null when the build does not carry it.PropertyThirdPartyNotices
PropertyReuse
PropertyLicences
LICENSES, in name order; empty when the folder is not carried.Admin.LicenceText
MethodLicenceText(string Name, string Text)
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
MIT, ISC, BSD-3-Clause.PropertyText
Admin.PageArchiveEntry
MethodPageArchiveEntry(PagePath Path, string Source, IReadOnlyList<Pages.PageStateValue> State, string SeedHash)
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
PropertySource
PropertyState
PropertySeedHash
PropertySourceBytes
PropertyStateKeys
Admin.PageArchiveFormat
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
application_id every archive carries: the bytes uoas.FieldVersion
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
FieldPageStateTable
FieldCreatePages
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
FieldCreatePageState
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)
Parameters
version- The archive's
user_version, which must be 1 or 2.
PropertyPageStateColumns
Admin.PageArchiveReadResult
MethodPageArchiveReadResult(IReadOnlyList<Admin.PageArchiveEntry> Pages, IReadOnlyList<string> Problems)
Parameters
Pages- The validated pages, in key order; empty when
Problemsis not. Problems- Every rule the archive broke, up to the reporting limit.
PropertyPages
Problems is not.PropertyProblems
PropertySucceeded
Admin.PageArchiveReader
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>)
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
MethodRead(byte[] archive)
Parameters
archive- The uploaded bytes.
Returns
Admin.PageArchiveWriter
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)
Parameters
pages- The pages to write, ordered or not; the writer sorts by key.
Returns
Admin.RestoreEndpoint
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)
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)
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
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)
Parameters
context- The request being answered.
pages- The page store.
antiforgery- Mints the form's token.
MethodScrubAsync(HttpContext context, Editor.PageEditor pages, ILoggerFactory loggers)
Parameters
context- The request being answered.
pages- The page store.
loggers- Names the log category.
Admin.SqliteStatement
MethodExecute(SqliteConnection connection, string sql)
Parameters
connection- The connection to run it on.
sql- The SQL to run.
Assistant
Assistant.AccountBalanceClient
/user/balance endpoint.MethodAccountBalanceClient(HttpClient, Assistant.AssistantOptions)
/user/balance endpoint.MethodGetAsync(CancellationToken)
Inherited from Assistant.IAccountBalanceClient.GetAsync.
Parameters
cancellationToken- Cancelled when the caller stops waiting.
Returns
Assistant.AccountBalanceSampler
MethodAccountBalanceSampler(IServiceScopeFactory, Assistant.AssistantMetrics, Assistant.AssistantOptions, ILogger<Assistant.AccountBalanceSampler>)
MethodSampleAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancelled when the host stops.
Assistant.ApprovalRequest
MethodApprovalRequest(string Name, string Description, string Arguments)
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
PropertyDescription
PropertyArguments
Assistant.AssistantConversationPage
MethodWriteInterruptAsync(HttpContext, Assistant.OwnerInterrupt, AntiforgeryTokenSet, long)
MethodWriteContinuationAsync(HttpContext, Assistant.OwnerInterrupt, Assistant.ContinuationRequest, AntiforgeryTokenSet, long)
Assistant.AssistantEndpoint
MethodInterruptAsync(HttpContext, long, string, Assistant.IConversationStore, Assistant.OwnerInterruptCoordinator)
MethodMessageContentAsync(HttpContext, long, long, Assistant.IConversationStore)
MethodValidatedOwnerAsync(HttpContext context, long id, Assistant.IConversationStore conversations, string expiredTitle)
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
Assistant.AssistantFetcher
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)
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)
url anonymously and returns the response, or a failure value.Inherited from Assistant.IAssistantFetcher.FetchAsync.
Parameters
url- An absolute
httporhttpsURL. cancellationToken- Cancelled when the tool's budget or the run ends.
MethodViewAsync(string, Authentication.ViewToken, CancellationToken)
Inherited from Assistant.IAssistantFetcher.ViewAsync.
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
/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
MethodListAsync(HttpContext context, Assistant.IMemoryStore memories, IAntiforgery antiforgery, Assistant.AssistantOptions options)
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)
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)
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)
Parameters
context- The response being written.
id- The memory to forget.
memories- The store the memory is deleted from.
Assistant.AssistantMetrics
PropertyInstruments
AssistantMetricsTests listens
to the meter to prove this list and the registrations below agree.
FieldStepBuckets
assistant.run.steps, in steps.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
assistant.run.tool_calls, in calls.Assistant:MaxToolCalls for the same reason (`metrics-one-panel-per-instrument`).FieldRunDurationBuckets
assistant.run.duration, in seconds.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
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
assistant.tool.duration, in seconds.Assistant:ToolTimeoutSeconds when it is not; the top boundary is past that cap
(`metrics-one-panel-per-instrument`).
FieldEstimateErrorBuckets
assistant.context.estimate.error, in tokens.+Inf (`metrics-one-panel-per-instrument`).
FieldMemoryCountBuckets
FieldUnknownTool
FieldNoKind
FieldShapedMasked
FieldShapedTrimmed
FieldExhaustedContext
FieldExhaustedProvider
FieldExhaustedOutput
MethodRecordTool(ToolDefinition tool, bool success, TimeSpan duration)
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)
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)
Parameters
kind- One of ShapedMasked or ShapedTrimmed.
MethodRecordBudgetExhausted(string cause)
Parameters
cause- One of ExhaustedContext, ExhaustedProvider or ExhaustedOutput.
MethodRecordToolTruncated(string tool)
Parameters
tool- The registered tool's name, or UnknownTool.
MethodRecordMemoryRecall(int memories, int characters)
Parameters
memories- The memories the run was given.
characters- What the block cost.
MethodRecordMemoryWrite(string operation, MemoryKind? kind, bool success)
Parameters
operation- The tool:
remember,updateorforget. 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)
Parameters
credits- The currencies the last sample could read.
Assistant.AssistantNavigation
FieldLabel
MethodNav(HttpContext context)
Parameters
context- The request whose path decides the current item.
Assistant.AssistantOptions
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
/models.PropertyModelsTimeoutSeconds
PropertyMinOutputTokens
PropertyBalanceTimeoutSeconds
PropertyBalanceSampleSeconds
PropertyMaxPageChars
PropertyMaxToolArgumentChars
PropertyMaxMemoriesPerOwner
remember refuses.PropertyMaxMemoryChars
PropertyMaxMemorySearchResults
PropertyMaxMemoryQueryTerms
PropertyWritablePathPrefix
PropertyMaxSearchMatches
search_pages call may return.PropertyDefaultListLimit
limit.PropertyMaxListLimit
PropertyShellMatchLimit
grep may show before it says there are more.PropertyShellDefaultLines
head and tail show when no count is given.MethodFromConfiguration(IConfiguration configuration)
Assistant.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Assistant into the caller's report.Parameters
reader- A reader opened on
Assistant, which the caller completes.
Assistant.AssistantOptionsValidator
MethodValidate(string, Assistant.AssistantOptions)
Inherited from IValidateOptions`1.Validate.
Assistant.ContinuationRequest
MethodContinuationRequest(string Budget, int Limit, int Window, string Message)
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
PropertyLimit
PropertyWindow
PropertyMessage
Assistant.Conversation
Assistant.ConversationListItem
MethodConversationListItem(long, string, string, DateTimeOffset, string)
Assistant.CurrencyCredit
MethodCurrencyCredit(string Currency, double Amount)
Parameters
Currency- The currency code the provider reported.
Amount- The total available credit in that currency.
PropertyCurrency
PropertyAmount
Assistant.IAccountBalanceClient
MethodGetAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancelled when the caller stops waiting.
Returns
Assistant.IAssistantFetcher
fetch and view.MethodFetchAsync(string url, CancellationToken cancellationToken)
url anonymously and returns the response, or a failure value.Parameters
url- An absolute
httporhttpsURL. cancellationToken- Cancelled when the tool's budget or the run ends.
MethodViewAsync(string url, Authentication.ViewToken token, CancellationToken cancellationToken)
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
Assistant.IConversationStore
MethodAppendMessageAsync(long, string, Assistant.MessageInput, CancellationToken)
MethodOpenInterruptAsync(string runId, string kind, string toolCallId, string requestJson, CancellationToken cancellationToken)
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
MethodGetInterruptAsync(string runId, CancellationToken cancellationToken)
Parameters
runId- The run whose interrupt is read.
cancellationToken- The run's token.
MethodGetPendingInterruptAsync(long conversationId, string owner, CancellationToken cancellationToken)
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)
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)
Parameters
conversationId- The conversation.
owner- The signed-in owner.
runId- The paused run.
cancellationToken- The request's token.
Returns
MethodFailPendingInterruptAsync(string runId, string failureCode, CancellationToken cancellationToken)
Parameters
runId- The run that stopped.
failureCode- Why it stopped.
cancellationToken- The caller's token.
MethodRecordToolCallAsync(string, CancellationToken)
Assistant.IMemoryStore
MethodRecallAsync(string owner, string queryTerms, int limit, CancellationToken cancellationToken)
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)
Parameters
owner- The account whose memories are read.
conversationId- The conversation whose recall is sticky.
cancellationToken- Cancels the query.
MethodPinnedAsync(string owner, CancellationToken cancellationToken)
Parameters
owner- The account whose memories are read.
cancellationToken- Cancels the query.
MethodListAsync(string owner, CancellationToken cancellationToken)
Parameters
owner- The account whose memories are read.
cancellationToken- Cancels the query.
MethodGetAsync(string owner, long id, CancellationToken cancellationToken)
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)
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)
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)
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)
Parameters
owner- The account the memory belongs to.
id- The memory to forget.
cancellationToken- Cancels the delete.
Returns
MethodTouchAsync(string owner, IReadOnlyList<long> ids, long conversationId, CancellationToken cancellationToken)
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)
Parameters
owner- The account to count.
cancellationToken- Cancels the count.
MethodClearProvenanceAsync(long conversationId, CancellationToken cancellationToken)
Parameters
conversationId- The conversation being deleted.
cancellationToken- Cancels the update.
Returns
MethodDeleteForOwnerAsync(string owner, CancellationToken cancellationToken)
Parameters
owner- The account being removed.
cancellationToken- Cancels the delete.
Returns
Assistant.IPageStoreReader
MethodTreeAsync(bool includeDeleted, CancellationToken cancellationToken)
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)
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)
Parameters
path- The node to read.
cancellationToken- The run's token.
MethodHistoryAsync(PagePath path, CancellationToken cancellationToken)
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)
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
MethodGetAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancelled when the host stops.
Returns
Assistant.InterruptPayloads
MethodWrite(object payload)
Parameters
payload- The value to store.
MethodApproval(string requestJson)
Parameters
requestJson- The stored request.
MethodContinuation(string requestJson)
Parameters
requestJson- The stored request.
MethodResolution(string resolutionJson)
Parameters
resolutionJson- The stored resolution.
Assistant.InterruptResolutionResult
FieldResolved
FieldNotFound
FieldConflict
Assistant.LineMatch
MethodLineMatch(PagePath Path, int Line, string Text)
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
PropertyLine
PropertyText
Assistant.LineMatches
MethodLineMatches(IReadOnlyList<Assistant.LineMatch> Matches, bool Truncated)
Parameters
Matches- The matching lines, in key then line order.
Truncated- Whether a limit stopped the scan before the sources ran out.
PropertyMatches
PropertyTruncated
Assistant.MemoryEdit
PropertyMemoryId
PropertyVersion
PropertyKind
PropertyContent
PropertyEditedAt
PropertySourceConversationId
Assistant.MemoryEntry
PropertyId
update_memory and forget_memory.PropertyOwner
PropertyKind
preference, fact, feedback or
reference.PropertyContent
PropertyVersion
PropertyPinned
PropertySourceConversationId
PropertySourceRunId
PropertyCreatedAt
PropertyUpdatedAt
PropertyLastRecalledAt
PropertyLastRecalledConversationId
PropertyRecallCount
Assistant.MemorySource
MethodMemorySource(long ConversationId, string RunId)
Parameters
ConversationId- The conversation the write happened in.
RunId- The run that made the call.
PropertyConversationId
PropertyRunId
Assistant.MemoryWriteResult
MethodMemoryWriteResult(bool IsSuccess, MemoryCandidate Memory, string Error)
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
PropertyMemory
PropertyError
MethodStored(MemoryCandidate memory)
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)
Parameters
error- The sentence the tool result carries.
Assistant.Message
MethodToChatMessage()
Assistant.MessageInput
MethodMessageInput(string, string, string, string, string, string, string)
Assistant.ModelWindowRead
MethodModelWindowRead(long? ContextWindow, int? MaximumOutputTokens, Assistant.ModelWindowReason Reason)
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
PropertyMaximumOutputTokens
PropertyReason
PropertyUnknown
PropertyIsAvailable
MethodOk(long, int)
MethodFailed(Assistant.ModelWindowReason)
MethodSameAs(Assistant.ModelWindowRead other)
other.Parameters
other- The read to compare with.
Returns
Assistant.ModelWindowReason
FieldOk
FieldModelMissing
FieldIncomplete
FieldTimeout
FieldUnreachable
FieldError
FieldInvalid
FieldUnknown
Assistant.ModelWindowSampler
MethodModelWindowSampler(IServiceScopeFactory, Assistant.ModelWindowSource, Assistant.AssistantOptions, ILogger<Assistant.ModelWindowSampler>)
PropertyBudget
PropertyRead
Assistant.ModelWindowSource
assistant-the-budget-is-window-minus-reply).
PropertyRead
PropertyBudget
MethodRecord(Assistant.ModelWindowRead read, int minimumOutputTokens)
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)
Parameters
budget- The budget every read answers with.
Assistant.OpenAiChatCompletionClient
MethodOpenAiChatCompletionClient(HttpClient, Assistant.AssistantOptions, ILogger<Assistant.OpenAiChatCompletionClient>)
MethodNamesContextLength(string body)
Parameters
body- The provider's error body.
Returns
Assistant.OwnerInterrupt
PropertyToolCallId
PropertyRequestJson
PropertyResolutionJson
Assistant.OwnerInterruptCoordinator
MethodWaitAsync(string runId, CancellationToken cancellationToken)
Parameters
runId- The run whose interrupt is pending.
cancellationToken- The run's token.
MethodSignal(string runId)
Parameters
runId- The run whose interrupt was resolved.
Returns
Assistant.OwnerInterruptKind
FieldApproval
FieldContinuation
Assistant.OwnerInterruptStatus
Assistant.OwnerResolution
MethodOwnerResolution(string Decision)
Parameters
Decision- The word the kind's form asked for.
PropertyDecision
Assistant.PageAuthorPrompt
Assistant.PageHistory
MethodPageHistory(bool Exists, bool IsDeleted, IReadOnlyList<Pages.PageRevisionSummary> Revisions)
Parameters
Exists- Whether a head exists, a tombstone's included.
IsDeleted- Whether the head is a tombstone.
Revisions- The retained revisions, newest first.
PropertyExists
PropertyIsDeleted
PropertyRevisions
PropertyMissing
Assistant.PageNode
MethodPageNode(PagePath Path, bool IsFolder, bool IsPage, bool IsShellFile, bool IsDeleted, bool CanWrite, Pages.PageImageState? State)
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
PropertyIsFolder
PropertyIsPage
PropertyIsShellFile
PropertyIsDeleted
PropertyCanWrite
PropertyState
Assistant.PagePathPolicy
Assistant:WritablePathPrefix.
PropertyReserved
MethodValidatePrefix(string prefixText)
Parameters
prefixText- The prefix the model asked for, or null for none.
MethodIsReserved(PagePath)
MethodCanWrite(PagePath)
MethodShadowedBy(PagePath)
Assistant.PageRead
MethodPageRead(PagePath Path, bool IsShellFile, bool CanWrite, Pages.PageImageState? State, string Text, Pages.PageTemplate Page)
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
PropertyIsShellFile
PropertyCanWrite
PropertyState
PropertyText
PropertyPage
Assistant.PageSourceSearch
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)
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
Assistant.PageStoreReader
MethodPageStoreReader(Editor.PageEditor pages, Assistant.PagePathPolicy paths)
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)
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)
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)
Inherited from Assistant.IPageStoreReader.ReadAsync.
Parameters
path- The node to read.
cancellationToken- The run's token.
MethodHistoryAsync(PagePath, CancellationToken)
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)
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
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)
Tools; this class
opens the per-call scope, builds the services a tool may use and hands the validated arguments over.
PropertyDefinitions
MethodChangesPages(string toolName)
Parameters
toolName- The tool the model called, as the transcript stored it.
MethodRefuseBeforeApproval(string name, string argumentsJson)
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
MethodPathValidationResult(PagePath, string)
Assistant.ProviderException
MethodProviderException(string, string, Exception)
FieldContextWindowMismatch
Assistant.ProviderModelsClient
MethodProviderModelsClient(HttpClient, Assistant.AssistantOptions)
MethodGetAsync(CancellationToken)
Inherited from Assistant.IProviderModelsClient.GetAsync.
Parameters
cancellationToken- Cancelled when the host stops.
Returns
MethodParse(string body, string model)
Parameters
body- The JSON the provider answered with.
model- The configured model name.
Returns
Assistant.QueuedRun
MethodQueuedRun(long, string, string)
Assistant.Run
PropertyPromptTokens
PropertyCompletionTokens
PropertyCachedTokens
PropertyReasoningTokens
PropertyOutputTokens
PropertyEstimatedTokens
PropertyMaxTokens
max_tokens, which is the allowance that step had.PropertyRequestBytes
PropertyLastPromptTokens
PropertyStepLimit
PropertyToolCallLimit
MethodToUsage()
Assistant.RunBudget
FieldSteps
FieldToolCalls
FieldToolCallsPerStep
MethodSentence(string budget, int limit, int window)
Parameters
budget- One of the budget constants.
limit- The limit the run reached.
window- How much a continuation adds.
Assistant.RunEvent
MethodRunEvent(string, long, string, string)
Assistant.RunJournalCleanupService
MethodRunJournalCleanupService(Assistant.RunRegistry, ILogger<Assistant.RunJournalCleanupService>)
Assistant.RunProcessor
MethodRunProcessor(IServiceScopeFactory, Assistant.IChatCompletionClient, Assistant.PageToolExecutor, Assistant.RunRegistry, Assistant.OwnerInterruptCoordinator, Assistant.AssistantMetrics, Assistant.AssistantOptions, Assistant.ModelWindowSampler, Users.IUserStore, Authentication.ViewTokenStore, ILogger<Assistant.RunProcessor>)
MethodWaitAsync(Assistant.QueuedRun, Assistant.RunStream, int, string, string, object, CancellationToken)
Returns
Assistant.RunQueue
MethodRunQueue(Assistant.AssistantOptions)
Assistant.RunRegistry
MethodRunRegistry(Assistant.AssistantOptions, TimeProvider)
Assistant.RunStartResult
MethodRunStartResult(Assistant.RunStartStatus, string, long?)
Assistant.RunStartStatus
Assistant.RunStatus
FieldAwaitingOwner
MethodIsActive(string status)
Parameters
status- A stored status.
Assistant.RunStream
MethodRunStream(string, Assistant.AssistantOptions, TimeProvider)
MethodDispose()
Assistant.RunWorker
MethodRunWorker(Assistant.RunQueue, IServiceScopeFactory, Assistant.AssistantOptions, ILogger<Assistant.RunWorker>)
Assistant.SqliteConversationStore
MethodSqliteConversationStore(Storage.StorageDbContext, TimeProvider, ILogger<Assistant.SqliteConversationStore>)
Assistant.SqliteMemoryStore
MethodSqliteMemoryStore(Storage.StorageDbContext, Assistant.AssistantOptions, TimeProvider)
Assistant.ToolContext
MethodToolContext(string Owner, long ConversationId, string RunId)
Parameters
Owner- The account the run belongs to.
ConversationId- The conversation the run is in.
RunId- The run making the call.
PropertyOwner
PropertyConversationId
PropertyRunId
PropertySource
Assistant.ToolExecutionResult
MethodToolExecutionResult(bool, string, string)
Assistant.Shell
Assistant.Shell.IShellOutput
PropertyMatchLimit
PropertyListingLimit
PropertyTruncated
PropertyText
MethodLine(string text)
Parameters
text- The line, without its line break.
MethodRaw(string text)
Parameters
text- The text.
MethodNote(string note)
Parameters
note- The note, without its brackets.
MethodStopped(string note)
Parameters
note- The note, without its brackets.
Assistant.Shell.ShellApplet
PropertyName
PropertyUsage
PropertyDescription
PropertyNotes
PropertySyntax
MethodRunAsync(ShellCommandLine line, Assistant.Shell.ShellContext context, CancellationToken cancellationToken)
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
MethodShellContext(ShellCommandLine line, IReadOnlyList<Assistant.PageNode> paths, Assistant.IPageStoreReader store, Assistant.Shell.IShellOutput output, Assistant.Shell.ShellRegistry registry, Assistant.AssistantOptions options)
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
helpreads. options- The assistant's configured limits, for the defaults an applet uses.
PropertyLine
PropertyPaths
PropertyStore
PropertyOutput
PropertyRegistry
help reads.PropertyOptions
Assistant.Shell.ShellExpansion
MethodShellExpansion(Assistant.PagePathPolicy paths)
Parameters
paths- The policy, which says what a key may be.
MethodExpandAsync(IReadOnlyList<ShellArgument> arguments, Assistant.IPageStoreReader store, CancellationToken cancellationToken)
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
MethodShellOutcome(bool IsSuccess, string Output, bool Truncated, string Summary, string Error)
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
PropertyOutput
PropertyTruncated
PropertySummary
PropertyError
MethodAnswered(string output, bool truncated, string summary)
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)
Parameters
error- The refusal.
summary- One line for the tool result's summary.
Assistant.Shell.ShellOutput
PropertyMatchLimit
Inherited from Assistant.Shell.IShellOutput.MatchLimit.
PropertyListingLimit
Inherited from Assistant.Shell.IShellOutput.ListingLimit.
PropertyTruncated
Inherited from Assistant.Shell.IShellOutput.Truncated.
PropertyText
Inherited from Assistant.Shell.IShellOutput.Text.
MethodLine(string)
Inherited from Assistant.Shell.IShellOutput.Line.
Parameters
text- The line, without its line break.
MethodRaw(string)
Inherited from Assistant.Shell.IShellOutput.Raw.
Parameters
text- The text.
MethodNote(string)
Inherited from Assistant.Shell.IShellOutput.Note.
Parameters
note- The note, without its brackets.
MethodStopped(string)
Inherited from Assistant.Shell.IShellOutput.Stopped.
Parameters
note- The note, without its brackets.
Assistant.Shell.ShellReading
MethodPagesAsync(IReadOnlyList<Assistant.PageNode> paths, Assistant.IPageStoreReader store, string command, CancellationToken cancellationToken)
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
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)
Parameters
applets- Every applet the shell answers.
PropertyAll
MethodFind(string name)
Parameters
name- The command word.
Assistant.Shell.ShellResult
MethodShellResult(bool IsSuccess, string Summary, string Error)
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
PropertySummary
PropertyError
MethodOk(string summary)
Parameters
summary- One line for the tool result's summary.
MethodRefused(string error, string summary)
Parameters
error- The refusal.
summary- One line for the tool result's summary.
Assistant.Shell.ShellRunner
PropertyRegistry
help reads.MethodRunAsync(string text, Editor.PageEditor pages, Assistant.PagePathPolicy paths, Assistant.AssistantOptions options, ContextBudget budget, CancellationToken cancellationToken)
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)
Parameters
character- The operator the line carried.
Assistant.Shell.ShellText
MethodSplit(string text)
"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)
Parameters
text- The text to number.
Assistant.Shell.Applets
Assistant.Shell.Applets.CatApplet
Assistant.Shell.Applets.DiffApplet
Assistant.Shell.Applets.FindApplet
Assistant.Shell.Applets.FindExpression
find line asks for: the tests, joined by and.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
Assistant.Shell.Applets.HeadApplet
Assistant.Shell.Applets.HeadOrTailApplet
MethodTake(string[] lines, int count)
Parameters
lines- Every line of the page.
count- How many to take.
Assistant.Shell.Applets.HelpApplet
Assistant.Shell.Applets.LsApplet
Assistant.Shell.Applets.StatApplet
Assistant.Shell.Applets.TailApplet
Assistant.Shell.Applets.WcApplet
Assistant.Tools
Assistant.Tools.AssistantTool
PropertySpec
MethodRunAsync(Assistant.Tools.ToolValues values, Assistant.Tools.ToolServices services, CancellationToken cancellationToken)
Parameters
values- The validated arguments.
services- The caller and the services this call may use.
cancellationToken- The run's token.
Assistant.Tools.CheckScriptTextTool
Assistant.Tools.CheckScriptTool
Assistant.Tools.DeletePageTool
Assistant.Tools.DiffPageTool
Assistant.Tools.EditPageTool
Assistant.Tools.FetchTool
Assistant.Tools.ForgetMemoryTool
Assistant.Tools.ListPagesTool
Assistant.Tools.ListRevisionsTool
Assistant.Tools.MemoryTools
Assistant.Tools.PageToolData
FieldHashRefusal
MethodLimitRefusal(Assistant.AssistantOptions options)
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)
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
MethodProjectSource(string content, int? requestedStart, int? requestedEnd, ContextBudget 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
Assistant.Tools.PageToolData.ProjectedSource
MethodProjectedSource(string Text, int StartLine, int EndLine, int TotalLines, bool Truncated)
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
| , or a
head-and-tail window when they were too long.
PropertyStartLine
PropertyEndLine
PropertyTotalLines
PropertyTruncated
Assistant.Tools.ReadPageTool
Assistant.Tools.ReadRevisionTool
Assistant.Tools.ReferenceTool
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
Assistant.Tools.RestoreRevisionTool
Assistant.Tools.SearchMemoriesTool
Assistant.Tools.SearchPagesTool
Assistant.Tools.ShellTool
Assistant.Tools.ToolPaths
MethodResolveRead(Assistant.Tools.ToolSpec spec, Assistant.Tools.ToolValues values, string argument, Assistant.Tools.ToolServices services)
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)
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)
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)
Parameters
path- The path to describe.
Assistant.Tools.ToolRegistry
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)
Parameters
tools- Every tool the assistant answers.
PropertyDefault
PropertyAll
PropertyDefinitions
MethodFind(string name)
Parameters
name- The tool name.
Assistant.Tools.ToolResults
MethodToolResults(ContextBudget budget)
Parameters
budget- The content budget one tool result may spend.
MethodSuccess(object data, string summary)
Parameters
data- What the tool produced.
summary- One line for the transcript.
MethodFailure(string error, string summary)
Parameters
error- The refusal.
summary- One line for the transcript.
MethodRefusal(string error, string summary)
Parameters
error- The refusal.
summary- One line for the transcript.
Returns
MethodBounded(object envelope, string summary, bool success)
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
MethodToolServices(IServiceProvider scope, Assistant.ToolContext context, Assistant.PagePathPolicy paths, Assistant.AssistantOptions options, ContextBudget budget, Assistant.AssistantMetrics metrics, Assistant.IAssistantFetcher fetcher)
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
PropertyPaths
PropertyOptions
PropertyBudget
PropertyMetrics
PropertyFetcher
fetch.PropertyPages
PropertyStore
PropertyEditorPath
PropertyMemories
PropertyViews
PropertySite
view resolves against.PropertyResults
PropertyReference
Assistant.Tools.ToolSpec
MethodToolSpec(string Name, string Description, bool NeedsApproval, IReadOnlyList<ToolArgumentSchema> Arguments)
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
PropertyDescription
PropertyNeedsApproval
PropertyArguments
PropertyVerb
PropertyWrites
PropertyPathArgument
Assistant.Tools.ToolValues
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)
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)
Parameters
name- The argument's name.
MethodInteger(string name)
Parameters
name- The argument's name.
MethodBoolean(string name)
Parameters
name- The argument's name.
MethodHas(string name)
Parameters
name- The argument's name.
MethodArray(string name)
Parameters
name- The argument's name.
MethodRequiredString(string name)
Parameters
name- The argument's name.
MethodRequiredInteger(string name)
Parameters
name- The argument's name.
Assistant.Tools.UpdateMemoryTool
Assistant.Tools.ViewTool
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
Authentication
Authentication.AuthTicket
PropertyKey
PropertyUserName
PropertyProtectedTicket
PropertyExpiresAt
Authentication.AuthTicketCleanupService
MethodAuthTicketCleanupService(Authentication.AuthTicketStore, TimeProvider, ILogger<Authentication.AuthTicketCleanupService>)
Authentication.AuthTicketStore
MethodAuthTicketStore(IServiceScopeFactory)
MethodFind(string key)
Parameters
key- The cookie's key.
Returns
null when the key is unknown.MethodAdd(Authentication.AuthTicket ticket)
Parameters
ticket- The row to add.
MethodUpdate(string key, string userName, string protectedTicket, DateTime expiresAt)
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
MethodRemove(string key)
Parameters
key- The cookie's key.
Returns
MethodRemoveExpired(DateTime now)
Parameters
now- The current UTC time.
Returns
Authentication.AuthenticationExtensions
FieldViewSchemeSelector
MethodAddEditorAuthentication(IServiceCollection services, IWebHostEnvironment environment, Authentication.AuthenticationOptions authentication)
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
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)
Parameters
context- The request, before its response is written.
next- The rest of the pipeline, which decides the response.
MethodLog(HttpContext context, string reason)
Parameters
context- The request being refused.
reason- What was refused, in a few words for the journal.
MethodLog(HttpContext context, string reason, string account)
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
Authentication.PropertyTicketLifetime
PropertyLogin
MethodFromConfiguration(IConfiguration configuration)
Authentication.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Authentication into the caller's report.Parameters
reader- A reader opened on
Authentication, which the caller completes.
Authentication.EditorPolicy
FieldName
FieldSecurityStampClaim
Authentication.LocalRedirect
MethodSafe(string returnUrl)
Parameters
returnUrl- The value the browser supplied.
MethodIsSafe(string returnUrl)
Parameters
returnUrl- The value to test.
Authentication.LoginEndpoint
MethodGetAsync(HttpContext, IAntiforgery)
MethodPostAsync(HttpContext, Users.IUserStore, Users.IPasswordService, IAntiforgery, IAuthenticationService, Pages.IPageSessionStore, Authentication.PageSessionCookieOptions, ILoggerFactory)
MethodLogoutConfirmationAsync(HttpContext context, IAntiforgery antiforgery)
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)
MethodWriteExpiredFormAsync(HttpContext context, IAntiforgery antiforgery)
Parameters
context- The rejected sign-in POST.
antiforgery- Mints the replacement token.
Authentication.LoginRateLimitOptions
Authentication:Login.PropertyPermitLimit
PropertyWindow
Authentication.LoginRateLimitPolicy
FieldName
FieldBuckets
LoginRateLimitPolicy.BucketMask can mask where a modulo would divide. 1024
buckets bound the limiter's dictionary.
MethodPartitionFor(IPAddress address)
Parameters
address- The client's address, or null when the server could not supply one.
Returns
Authentication.LoginRedirect
/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)
/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
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()
Returns
MethodRead(HttpContext context, Authentication.PageSessionCookieOptions options)
Parameters
context- The request being answered.
options- The cookie's name.
Returns
null when the cookie is absent or malformed.MethodWrite(HttpContext context, string sessionId, Authentication.PageSessionCookieOptions options)
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)
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)
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
MethodClearAsync(HttpContext context, Pages.IPageSessionStore store, Authentication.PageSessionCookieOptions options, CancellationToken cancellationToken)
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
MethodPageSessionCookieOptions(string Name, CookieSecurePolicy SecurePolicy)
Parameters
Name- The cookie's name.
SecurePolicy- Whether the cookie is only sent over HTTPS.
PropertyName
PropertySecurePolicy
FieldDefaultName
MethodFor(IWebHostEnvironment environment)
Parameters
environment- The host environment.
Authentication.SignedInOwner
MethodOf(HttpContext context)
Parameters
context- The request being answered.
Returns
Authentication.StoredTicketDataFormat
MethodStoredTicketDataFormat(ISecureDataFormat<AuthenticationTicket> inner, Authentication.AuthTicketStore tickets, IHttpContextAccessor http, string cookieName)
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)
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
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)
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
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)
Parameters
context- The request.
next- The rest of the pipeline.
Authentication.ViewToken
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
FieldAuthenticationScheme
FieldHeaderScheme
Authorization header.PropertySecret
Authorization: Bearer.PropertyRunId
PropertyOwner
PropertySecurityStamp
MethodCreate(string runId, string owner, string securityStamp)
Parameters
runId- The run's id.
owner- The account the run belongs to.
securityStamp- The account's stamp, read when the run started.
MethodToString()
Returns
Authentication.ViewTokenStore
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)
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)
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
Exceptions
InvalidOperationException- Every active run already holds one.
MethodForRun(string runId)
Parameters
runId- The run's id.
MethodTryResolve(string secret, ref Authentication.ViewToken token)
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)
Parameters
token- The token Mint returned.
PropertyCount
Configuration
Configuration.ConfigurationException
MethodConfigurationException(string)
Configuration.ConfigurationReader
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)
Parameters
configuration- The application configuration.
section- The section's path, such as
Pages:Render.
PropertySection
MethodFor(string key)
Parameters
key- The section's key.
MethodAt(string section)
Parameters
section- The section's path from the configuration root.
MethodExists()
MethodValueOrNull()
MethodHas(string key)
Parameters
key- The key, relative to this section.
MethodSectionOf(string key)
Parameters
key- The key, relative to this section.
MethodChildren(string key)
Parameters
key- The key, relative to this section.
MethodFail(string key, string problem)
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)
Parameters
problem- The whole sentence.
MethodFailIf(bool condition, string key, string problem)
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()
Exceptions
MethodText(string key, string example, bool allowEmpty)
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)
Parameters
key- The key, relative to this section.
MethodValue(string example, bool allowEmpty)
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)
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)
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)
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)
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)
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)
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
MethodReferenceAssembly(Documentation.ReferenceAssemblyInfo Info, int TypeCount, int EntryCount, XDocument Document, Lazy<string> Html)
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
PropertyTypeCount
PropertyEntryCount
PropertyDocument
PropertyHtml
Documentation.ReferenceAssemblyInfo
MethodReferenceAssemblyInfo(string Slug, string AssemblyName, string Title, string Description)
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
/admin/reference.PropertyAssemblyName
PropertyTitle
PropertyDescription
PropertyAll
Documentation.ReferenceDisplay
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
MethodKind(string id)
Parameters
id- A documentation id.
MethodBody(string id)
Parameters
id- A documentation id.
MethodWithoutParameters(string id)
Parameters
id- A documentation id.
MethodParameters(string id)
Parameters
id- A documentation id.
MethodOwner(string id)
Parameters
id- A documentation id.
MethodRelative(string id, string root)
Parameters
id- A documentation id.
root- The assembly name, which is its root namespace.
MethodTypeDisplay(string id, string root, IReadOnlyList<string> typeParameters)
Parameters
id- A type's id.
root- The assembly's root namespace.
typeParameters- The names from its
typeparamelements, in order.
MethodMemberDisplay(string id, string root, IReadOnlyList<string> typeParameters, IReadOnlyList<string> methodTypeParameters, IReadOnlyList<string> parameterNames)
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
paramelements, in order.
MethodMemberName(string id, string root, IReadOnlyList<string> methodTypeParameters)
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)
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)
Parameters
id- An id the corpus does not hold.
MethodCrefText(string id)
Parameters
id- A documentation id.
MethodKindName(char kind)
Parameters
kind- The letter.
Documentation.ReferenceDocIds
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)
Parameters
member- The reflected member.
MethodOf(Type type)
Parameters
type- The reflected type.
MethodMap(Assembly assembly)
Parameters
assembly- The assembly to scan.
Documentation.ReferenceDocument
MethodReferenceDocument(Documentation.ReferenceAssemblyInfo Info, XDocument Content, int TypeCount, int EntryCount, IReadOnlyDictionary<string, Documentation.ReferenceEntry> Entries)
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
PropertyContent
PropertyTypeCount
PropertyEntryCount
PropertyEntries
MethodBuild(Documentation.ReferenceAssemblyInfo info, XDocument source)
Parameters
info- The assembly the file belongs to.
source- The parsed file.
Exceptions
InvalidDataException- The file has no
memberselement.
Documentation.ReferenceEndpoint
/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)
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)
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
MethodReferenceEntry(string Id, string Anchor, string Kind, string Display, string Text, bool IsType)
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
PropertyAnchor
PropertyKind
PropertyDisplay
PropertyText
PropertyIsType
Documentation.ReferenceInheritance
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)
Parameters
documents- The corpus, already normalised and with its anchors.
logger- Where a summary line goes.
Documentation.ReferenceLibrary
/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
MethodReferenceLibrary(string directory, ILogger<Documentation.ReferenceLibrary> logger)
Parameters
directory- Where the assemblies' XML files sit.
logger- Where a missing or malformed file is reported.
PropertyAssemblies
MethodFind(string slug)
Parameters
slug- The segment under
/admin/reference.
MethodRender(string slug)
Parameters
slug- The segment under
/admin/reference.
MethodFindType(string name)
Parameters
name- What the model named.
MethodSearch(string query, int limit)
Parameters
query- What to look for, case-insensitively.
limit- The most matches to return.
PropertyContract
Documentation.ReferenceRenderer
XsltSettings.Default and a null resolver, so script blocks and document() are off.
MethodRender(XDocument document)
Parameters
document- The normalised document.
Documentation.ReferenceSearchMatch
MethodReferenceSearchMatch(string Type, string Member, string Kind, string Summary)
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
PropertyMember
PropertyKind
PropertySummary
Documentation.ReferenceText
MethodFlatten(XElement element)
Parameters
element- The element to flatten.
Documentation.ReferenceTypeLookup
MethodReferenceTypeLookup(Documentation.ReferenceTypeMatch Match, IReadOnlyList<Documentation.ReferenceTypeMatch> Candidates, Documentation.ReferenceTypeMatch Elsewhere)
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
PropertyCandidates
PropertyElsewhere
Documentation.ReferenceTypeMatch
MethodReferenceTypeMatch(Documentation.ReferenceAssemblyInfo Info, XElement Type)
Parameters
Info- The assembly.
Type- Its
typeelement.
PropertyInfo
PropertyType
type element.Editor
Editor.ConditionalPageSaveResult
MethodConditionalPageSaveResult(bool, string, IReadOnlyList<PageDiagnostic>)
Editor.PageEditor
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)
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)
Parameters
path- The canonical key to read.
cancellationToken- Cancels the read.
PropertyRuntimeId
MethodGetRevisionAsync(PagePath path, string hash, CancellationToken cancellationToken)
Parameters
path- The page the revision must belong to.
hash- The canonical hash a listing or a form carried.
cancellationToken- Cancels the read.
Returns
MethodAdoptAsync(PagePath path, string seedHash, CancellationToken cancellationToken)
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)
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
defaultwhen no page is waiting; a compile bounded by it can be given up on without losing the save.
Returns
MethodSaveSeedAsync(PagePath path, string template, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)
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)
MethodSaveSeedIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)
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
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>)
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
MethodSaveAsync(PagePath path, string template, CancellationToken cancellationToken, CancellationToken renderDeadline)
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
MethodSaveSeedAsync(PagePath path, string template, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)
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
MethodSaveIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, CancellationToken cancellationToken, CancellationToken renderDeadline)
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
ConditionalPageSaveResult.Saved false when the head moved.MethodSaveSeedIfRevisionAsync(PagePath path, string template, string expectedRevisionHash, string seedHash, CancellationToken cancellationToken, CancellationToken renderDeadline)
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
ConditionalPageSaveResult.Saved false when the head moved.MethodRecordSaveFailed(PagePath path, long start)
Parameters
path- The page that was saved.
start- When the save started.
MethodRecordSaved(PagePath path, Pages.PageImage image, long start)
Parameters
path- The page that was saved.
image- What compiling it produced.
start- When the save started.
Editor.SavedRevision
MethodSavedRevision(Pages.PageTemplate Revision, IReadOnlyList<PageDiagnostic> Diagnostics)
Parameters
Revision- The revision that became the page's head.
Diagnostics- The compiler's author-facing answer; empty when the page compiled cleanly.
PropertyRevision
PropertyDiagnostics
Errors
Errors.ErrorAudience
MethodPrefersJson(HttpRequest request)
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
MethodHandleAsync(HttpContext context)
Parameters
context- The failing request.
Errors.ErrorMessage
MethodErrorMessage(string Code, string Title, string Summary, IReadOnlyList<NavLink> Remedies)
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
PropertyTitle
PropertySummary
PropertyRemedies
MethodForStatus(int statusCode, bool isAuthenticated, string editorPath)
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)
Parameters
isAuthenticated- Whether the reader is signed in.
editorPath- The editor key the remedies link to.
MethodDefaultRemedies(bool isAuthenticated, string editorPath)
Parameters
isAuthenticated- Whether the reader is signed in.
editorPath- The editor's own key, which is configuration.
Errors.ErrorResponses
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)
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)
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)
Parameters
context- The failing request.
statusCode- The status to send.
message- What to say.
cancellationToken- Cancels the write.
MethodProblem(int statusCode, Errors.ErrorMessage message)
Parameters
statusCode- The status to send.
message- What to say.
Health
Health.AbandonedRenderHealthCheck
/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)
/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
/health response.MethodWriteAsync(HttpContext, HealthReport)
Health.StorageHealthCheck
MethodStorageHealthCheck(IServiceScopeFactory)
MethodCheckHealthAsync(HealthCheckContext, CancellationToken)
Inherited from IHealthCheck.CheckHealthAsync.
Html
Html.AntiforgeryField
MethodHidden(AntiforgeryTokenSet tokens)
Parameters
tokens- The tokens for this request.
Html.DiagnosticLine
MethodDiagnosticLine(string Text, PageDiagnosticSeverity? Severity, int? Line)
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
PropertySeverity
PropertyLine
MethodFrom(IReadOnlyList<PageDiagnostic> diagnostics)
Parameters
diagnostics- The diagnostics to show.
Returns
Html.Markup
Encode(value) and cannot reach for an unescaped string by accident.
MethodEncode(string value)
Parameters
value- The value to escape.
Returns
Html.PageLayout
MethodGutter(int lineCount)
Parameters
lineCount- The number of source lines, from Count.
MethodDiagnostics(IReadOnlyList<Html.DiagnosticLine> lines, bool linkToLines)
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
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
FieldShellClass
body carries, so a reader can tell it from a page.FieldShellLabelText
PropertyBaseStylesheets
/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)
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)
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
headlast, 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
nullto 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)
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.
MethodNav(string label, IReadOnlyList<NavLink> links, string className)
Parameters
label- The landmark's accessible name, which no other
navmay 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()
main landmark, which the skip link targets.MethodCloseMain()
MethodFooter()
MethodEnd()
MethodBeginAsync(HttpContext context, string title, string navigation, int statusCode, IReadOnlyList<string> stylesheets, string bodyClass, string head, CancellationToken cancellationToken)
main 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
headafter 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)
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
MethodEndAsync(HttpContext context, CancellationToken cancellationToken)
Parameters
context- The response being written.
cancellationToken- Cancels the write.
Html.SiteNavigation
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
FieldClass
nav carries, so the sheets can style it.MethodFor(HttpContext context)
Parameters
context- The request whose principal and path decide the items.
MethodNav(bool authenticated, string path, string query, string editorPath)
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.
MethodLinks(bool authenticated, string path, string query, string editorPath)
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.
MethodFooterLinks()
Http
Http.DisconnectGuard
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)
Parameters
app- The pipeline, after the exception handler and before the endpoints.
Http.MachineTrafficMetrics
FieldHealthPath
FieldScrapePath
MethodSkipAsync(HttpContext context, RequestDelegate next)
Parameters
context- The request being handled.
next- The rest of the pipeline.
Http.NotFound
Http.PageUrls
MethodPage(PagePath)
path.MethodEditor(PagePath path, string editorPath)
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)
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)
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)
path.Parameters
path- The page to compare.
from- The older revision.
to- The newer revision.
editorPath- The editor's own key.
MethodScrub(PagePath)
path, which is the shell's.Http.Redirect
MethodTo(HttpContext context, int status, string target)
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)
target.Http.ResponseWrite
MethodIsDisconnect(HttpContext context, Exception exception)
Parameters
context- The request being answered.
exception- The exception the write raised.
Http.SecurityHeaders
FieldContentSecurityPolicy
PropertyDefault
PropertyWithScripts
MethodApplyAsync(HttpContext, RequestDelegate)
MethodAllowScripts(HttpContext context)
Parameters
context- The response that is about to load a script.
MethodNoStore(HttpContext context)
Parameters
context- The response to mark.
MethodNoStoreIfAbsent(HttpContext context)
Parameters
context- The response to mark.
MethodIsOwned(string name)
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
Http.ShellCookies
FieldAuthentication
FieldAntiforgery
FieldSession
MethodIsOwned(string name)
name belongs to the shell rather than to a page.Parameters
name- The cookie name to test.
Returns
Logging
Logging.LogScope
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)
Parameters
name- The field's name, as it appears in the journal.
value- The value, or
nullwhen it is not known.
MethodGetEnumerator()
Inherited from IEnumerable`1.GetEnumerator.
MethodSystem.Collections.IEnumerable.GetEnumerator()
Inherited from IEnumerable.GetEnumerator.
Logging.RequestLogScope
MethodUseRequestLogScope(IApplicationBuilder app)
Parameters
app- The pipeline, before the exception handler.
MethodUseRequestLogSubject(IApplicationBuilder app)
Parameters
app- The pipeline, after authentication and routing.
Metrics
Metrics.ChartEndpoint
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)
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
MethodChartRenderer(Metrics.IMetricsSource source, Metrics.MetricsOptions options)
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)
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
Metrics.ChartResult
MethodChartResult(string Svg, string Reason)
Parameters
Svg- The drawing, or null when a query failed.
Reason- Why a query failed, or null when the drawing was made.
PropertySvg
PropertyReason
Metrics.ChartWindow
MethodChartWindow(DateTimeOffset Start, TimeSpan Length)
Parameters
Start- The left edge, snapped to the step.
Length- How far the window reaches.
PropertyStart
PropertyLength
FieldDefaultToken
PropertyDefaultLength
PropertyTokens
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
PropertyStep
PropertyRateRange
MethodAt(DateTimeOffset start, TimeSpan length)
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)
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)
Parameters
token- The token from the query string; null or unknown means the default.
MethodLengthForToken(string token)
Parameters
token- The token from the query string; null or unknown means the default.
MethodStepFor(TimeSpan length)
Parameters
length- How far the window reaches.
Metrics.ChartWindow.WindowToken
MethodWindowToken(string Token, TimeSpan Length)
Parameters
Token- The value carried in the
durationquery string, and the nav's label. Length- How far back the queries reach.
PropertyToken
duration query string, and the nav's label.PropertyLength
Metrics.Dashboard
MethodDashboard(Metrics.ChartRenderer renderer, TimeProvider time, Metrics.MetricsOptions options, ILogger<Metrics.Dashboard> logger)
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)
Parameters
window- The start and length to draw.
cancellationToken- Aborted when the request is abandoned.
MethodHref(Metrics.Panel panel, Metrics.ChartWindow window)
Parameters
panel- The panel.
window- The window.
Metrics.IMetricsSource
MethodQueryAsync(string query, DateTimeOffset from, DateTimeOffset to, TimeSpan step, CancellationToken cancellationToken)
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
Metrics.InstrumentKind
FieldHistogram
FieldCounter
FieldGauge
Metrics.MetricInstrument
MethodMetricInstrument(string Name, Metrics.InstrumentKind Kind, string Unit)
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
PropertyKind
PropertyUnit
Metrics.MetricsMatrix
MethodMetricsMatrix(IReadOnlyList<ChartSeries> Series)
Parameters
Series- The series, possibly empty when the query matched nothing.
PropertySeries
Metrics.MetricsOptions
Metrics.PropertyPrometheusUrl
PropertyTimeZone
PropertyQueryTimeout
PropertyCacheFor
PropertyMaxCachedWindows
MethodFromConfiguration(IConfiguration configuration)
Metrics.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Metrics into the caller's report.Parameters
reader- A reader opened on
Metrics, which the caller completes.
Metrics.MetricsUnavailable
MethodMetricsUnavailable(string Reason)
Parameters
Reason- Text for the banner, written for the person reading the page.
PropertyReason
Metrics.Panel
PropertyId
PropertyGroup
PropertyTitle
PropertyDescription
PropertyYTitle
PropertyChart
PropertyQueries
PropertyCellUnit
PropertyInstrumentName
PropertySourceInstruments
PropertyHostFamilies
PropertyPartsOfAWhole
Metrics.PanelChart
FieldHeatmap
FieldLine
FieldStackedArea
Metrics.PanelQuery
MethodPanelQuery(string Query, string Label)
Parameters
Query- The expression.
Label- The label a series without one takes.
PropertyQuery
PropertyLabel
FieldRange
Metrics.PrometheusNames
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)
Parameters
instrument- The instrument.
MethodBuckets(Metrics.MetricInstrument instrument)
Parameters
instrument- The instrument.
MethodSum(Metrics.MetricInstrument instrument)
Parameters
instrument- The instrument.
MethodTotal(Metrics.MetricInstrument instrument)
Parameters
instrument- The instrument.
Metrics.PrometheusSource
query_range API.NaN and the infinities hide.
MethodPrometheusSource(HttpClient http, ILogger<Metrics.PrometheusSource> logger, TimeSpan queryTimeout)
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)
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
Metrics.QueryResult
Metrics.StatusCatalogue
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
PropertyPanels
MethodFind(string id)
Parameters
id- The panel id, which is the instrument name for an instrument panel.
Returns
Metrics.StatusEndpoint
MethodHostLine()
MethodHandleAsync(HttpContext context, Metrics.Dashboard dashboard, TimeProvider time, CancellationToken cancellationToken)
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
MethodStatusGroup(string, IReadOnlyList<Metrics.StatusPanel>)
Metrics.StatusPage
MethodStatusPage(IReadOnlyList<Metrics.StatusPanel> Panels, string Banner)
Parameters
Panels- The drawings, in catalogue order.
Banner- Why some are missing, or null when everything answered.
PropertyPanels
PropertyBanner
Metrics.StatusPanel
MethodStatusPanel(Metrics.Panel Panel, string Svg)
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
PropertySvg
Pages
Pages.BodyBudget
MethodBodyBudget(int maxChars)
Parameters
maxChars- How much body the request may buffer before it is refused.
PropertyMaxChars
PropertyRemaining
MethodTryCharge(int chars)
Parameters
chars- The length of the text about to be written.
Returns
Pages.BuildInfo
PropertyCurrent
PropertyCommit
null when the build has none.Inherited from IBuildInfo.Commit.
Pages.CompileOptions
Pages:Compile.
PropertySlots
PropertyTimeoutSeconds
PropertyTimeout
MethodFromConfiguration(IConfiguration configuration)
Pages:Compile.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Compile into the caller's report.Parameters
reader- A reader opened on
Pages:Compile, which the caller completes.
Pages.EditorPaths
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)
Parameters
services- The request's services.
Exceptions
InvalidOperationException- The request has no editor key.
Pages.EmptyHttpFetchStream
MethodEmptyHttpFetchStream(HttpFetchFailure, Action<HttpFetchStream>)
PropertyStatus
Inherited from HttpFetchStream.Status.
PropertyTruncated
Inherited from HttpFetchStream.Truncated.
MethodReadLineAsync()
null when the stream has ended.Inherited from HttpFetchStream.ReadLineAsync.
Returns
null at end of stream.MethodCloseAsync()
Inherited from HttpFetchStream.CloseAsync.
Returns
Pages.IOutboundCredential
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
PropertyHeader
PropertyHeaderValue
MethodAppliesTo(Uri uri)
uri.Parameters
uri- The request or redirect target.
Pages.IPageBatchStore
MethodSaveBatchAsync(IReadOnlyList<Pages.PageBatchSave> pages, CancellationToken cancellationToken)
Parameters
pages- The pages to store, in key order.
cancellationToken- Cancels the write.
Returns
Pages.IPageBodySink
MethodStartAsync(PageResponse response, CancellationToken cancellationToken)
Parameters
response- What the page asked the response to be.
cancellationToken- Cancels the start.
MethodWriteAsync(ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken)
Parameters
bytes- The UTF-8 body to write.
cancellationToken- Cancels the write.
Pages.IPageFetcher
MethodFetchAsync(HttpFetchRequest request, string pagePath, CancellationToken aborted, CancellationToken deadline)
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
MethodStreamAsync(HttpFetchRequest request, string pagePath, CancellationToken aborted, CancellationToken deadline)
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
Pages.IPageReadStore
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)
Parameters
cancellationToken- Cancels the read.
Returns
MethodListAsync(string prefix, int limit, CancellationToken cancellationToken)
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
limit heads, in ordinal key order.MethodGetHeadAsync(string key, CancellationToken cancellationToken)
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no page has that key.MethodGetSourceAsync(string key, CancellationToken cancellationToken)
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no live page has that key.MethodListRevisionsAsync(string key, CancellationToken cancellationToken)
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
MethodGetRevisionSourceAsync(string key, string hash, CancellationToken cancellationToken)
Parameters
key- The canonical key the revision belongs to.
hash- The revision's hash.
cancellationToken- Cancels the read.
Returns
null when that page has no such revision.Pages.IPageRevisionStore
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)
Parameters
revision- The revision, already built with its id, hash and image.
cancellationToken- Cancels the write.
Returns
MethodTrySaveAsync(Pages.PageTemplate revision, string expectedHash, CancellationToken cancellationToken)
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
MethodFindAsync(string sessionId, CancellationToken cancellationToken)
Parameters
sessionId- The id from the visitor's cookie.
cancellationToken- Cancels the read.
Returns
null when the id names no live session.MethodEnsureAsync(string sessionId, string account, CancellationToken cancellationToken)
Parameters
sessionId- The id to mint.
account- The normalised account name, or
null. cancellationToken- Cancels the write.
Returns
MethodTouchAsync(string sessionId, CancellationToken cancellationToken)
Parameters
sessionId- The id that was touched.
cancellationToken- Cancels the write.
MethodDeleteAsync(string sessionId, CancellationToken cancellationToken)
Parameters
sessionId- The id to delete.
cancellationToken- Cancels the write.
Returns
MethodGetValueAsync(string sessionId, string pagePath, string key, CancellationToken cancellationToken)
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
null when the key is absent.MethodSetValueAsync(string sessionId, string pagePath, string key, string value, Pages.PageSessionCaps caps, CancellationToken cancellationToken)
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)
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
MethodListKeysAsync(string sessionId, string pagePath, CancellationToken cancellationToken)
Parameters
sessionId- The visitor's session.
pagePath- The canonical page key whose keys are listed.
cancellationToken- Cancels the read.
Returns
MethodListAllKeysAsync(string sessionId, CancellationToken cancellationToken)
Parameters
sessionId- The visitor's session.
cancellationToken- Cancels the read.
Returns
MethodRemoveExpiredAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancels the sweep.
Returns
Pages.IPageStateStore
MethodGetValueAsync(PagePath path, string key, CancellationToken cancellationToken)
Parameters
path- The page whose state is read.
key- The key to read.
cancellationToken- Cancels the read.
Returns
null when the key is absent.MethodSetValueAsync(PagePath path, string key, string value, CancellationToken cancellationToken)
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)
Parameters
path- The page whose state is written.
key- The key to remove.
cancellationToken- Cancels the write.
Returns
MethodListKeysAsync(PagePath path, CancellationToken cancellationToken)
Parameters
path- The page whose keys are listed.
cancellationToken- Cancels the read.
Returns
MethodGetValuesAsync(PagePath path, CancellationToken cancellationToken)
Parameters
path- The page whose state is read.
cancellationToken- Cancels the read.
Returns
Pages.IPageStore
MethodGetPageAsync(PagePath path, CancellationToken cancellationToken)
Parameters
path- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no page has that key.MethodListPagesAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancels the read.
Returns
MethodGetSourceAsync(PagePath path, CancellationToken cancellationToken)
Parameters
path- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no live page has that key.MethodSavePageAsync(Pages.PageTemplate template, CancellationToken cancellationToken)
Parameters
template- The page to store.
cancellationToken- Cancels the write.
MethodAdoptSeedAsync(PagePath path, string seedHash, CancellationToken cancellationToken)
Parameters
path- The canonical key.
seedHash- The hash of the seed the page's content already equals.
cancellationToken- Cancels the write.
Returns
MethodTrySavePageAsync(Pages.PageTemplate template, string expectedHash, CancellationToken cancellationToken)
Parameters
template- The new template and the image built from it.
expectedHash- The current head hash the caller read.
cancellationToken- Cancels the write.
Returns
MethodTrySetImageAsync(string revisionId, string expectedTemplate, Pages.PageImage image, CancellationToken cancellationToken)
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)
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
MethodAttachDeadline(CancellationToken deadline)
Parameters
deadline- The deadline's token; it outlives this use of it.
MethodAbandon()
Pages.IRenderBoundPageStorage
Pages.IRenderLifetimeAware
MethodAttachLifetime(Pages.RenderLifetime lifetime)
Parameters
lifetime- The render lifetime that owns this capability.
Pages.OutboundFetcher
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>)
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
MethodFetchAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, CancellationToken aborted, CancellationToken deadline)
aborted and deadline.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)
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
nullfor none. aborted- Cancelled when the caller gives up.
deadline- Cancelled when the caller's budget expires.
Returns
MethodFetchResponseAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, Pages.IOutboundCredential credential, CancellationToken aborted, CancellationToken deadline)
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
nullfor none. aborted- Cancelled when the caller gives up.
deadline- Cancelled when the caller's budget expires.
Returns
MethodStreamAsync(HttpFetchRequest request, string caller, Pages.OutboundOrigin origin, Pages.IOutboundCredential credential, Action<HttpFetchStream> aborted, CancellationToken deadline, CancellationToken onClosed)
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
nullfor none. aborted- Cancelled when the caller gives up.
deadline- Cancelled when the caller's lifetime ends.
onClosed- Records the completed stream.
Pages.OutboundHttpFetchStream
PropertyStatus
Inherited from HttpFetchStream.Status.
PropertyTruncated
Inherited from HttpFetchStream.Truncated.
MethodReadLineAsync()
null when the stream has ended.Inherited from HttpFetchStream.ReadLineAsync.
Returns
null at end of stream.MethodCloseAsync()
Inherited from HttpFetchStream.CloseAsync.
Returns
Pages.OutboundOrigin
User-Agent.FieldPage
IHttpFetch.FieldAssistant
fetch tool or its provider request.Pages.OutboundRedirect
MethodOutboundRedirect(int Status, string Location)
Parameters
Status- The status that sent the request on.
Location- Where it was sent, as the response named it.
PropertyStatus
PropertyLocation
Pages.OutboundResponse
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)
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
0when 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
0 when no response arrived.PropertyHeaders
PropertyBody
PropertyFailure
PropertyTruncated
PropertyRedirects
Pages.OutboundUserAgent
User-Agent every outbound request carries.FieldHost
FieldContact
MethodUserAgent(Pages.OutboundOrigin origin)
Parameters
origin- Whether page code or the assistant asked.
Pages.PageAssetMap
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
MethodForRequestAsync(HttpContext context, Pages.IPageReadStore store, int limit, CancellationToken cancellationToken)
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)
Parameters
store- Where the heads are read.
limit- The most rows to read.
cancellationToken- Cancels the read.
MethodResolve(IReadOnlyDictionary<string, string> map, string href)
Parameters
map- The request's asset map.
href- The link as the page or view wrote it.
Returns
Pages.PageAssetPolicy
MethodIsAsset(PageKind? kind)
Parameters
kind- The revision's kind; null means never judged.
MethodIsLibrary(PageKind? kind)
Parameters
kind- The revision's kind; null means never judged.
MethodIsWorker(PageKind? kind)
Parameters
kind- The revision's kind; null means never judged.
MethodIsServed(PageKind? kind)
Parameters
kind- The revision's kind; null means never judged.
Pages.PageAssetSeeder
MethodSeedAsync(Pages.IPageStore pages, Pages.PageSeeds seeds, CancellationToken cancellationToken)
Parameters
pages- The store to seed.
seeds- The pack this release ships.
cancellationToken- Bounds the reads and the writes.
MethodSeedPaths()
Pages.PageBatchResult
MethodPageBatchResult(IReadOnlyList<PagePath> Refused)
Parameters
Refused- The pages whose merged state would not fit; empty when the batch committed.
PropertyRefused
PropertyCommitted
PropertyIsCommitted
Pages.PageBatchSave
MethodPageBatchSave(Pages.PageTemplate Template, IReadOnlyList<Pages.PageStateValue> State)
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
PropertyState
Pages.PageBody
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)
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
nullwhen it cannot stream. aborted- The token from the request being served.
PropertyIsCommitted
PropertyCanStream
MethodAttachLifetime(Pages.RenderLifetime lifetime)
Parameters
lifetime- The lifetime the renderer opened for this request.
MethodAbandon()
MethodWrite(string text)
Parameters
text- The text to append; it is already escaped as the caller intended.
Exceptions
InvalidOperationException- The write overran the budget.
MethodGetText()
MethodMintOnce(ref string slot, Func<string> create)
Parameters
slot- Where the created value is kept, so a second read hands out the first.
create- Creates the value.
Returns
MethodFlushAsync(PageResponse response)
Parameters
response- What the layer asked the response to be.
MethodCompleteAsync()
Pages.PageBodySink
MethodPageBodySink(HttpContext, Pages.PageEnvironment, Pages.PageSessionRequest)
MethodStartAsync(PageResponse, CancellationToken)
Inherited from Pages.IPageBodySink.StartAsync.
Parameters
response- What the page asked the response to be.
cancellationToken- Cancels the start.
MethodWriteAsync(ReadOnlyMemory<byte>, CancellationToken)
Inherited from Pages.IPageBodySink.WriteAsync.
Parameters
bytes- The UTF-8 body to write.
cancellationToken- Cancels the write.
Pages.PageBudget
FieldMinimumTimeoutSeconds
MethodPageBudget(Pages.RenderOptions render, Pages.CompileOptions compile, Pages.StreamOptions stream)
Parameters
render- The render limits.
compile- The compile limits.
stream- The stream limits.
PropertyRenderOptions
PropertyCompileOptions
PropertyStreamOptions
MethodDescribeSeconds(TimeSpan budget)
Parameters
budget- The budget to describe.
Returns
PropertyRenderSlots
PropertyCompileSlots
PropertyStreamSlots
MethodDispose()
Inherited from IDisposable.Dispose.
Pages.PageCapabilities
MethodAdd<T>(T capability)
Type parameters
T- The capability interface.
Parameters
capability- The implementation; it may not be
null.
Returns
Exceptions
InvalidOperationException- The capability is already registered.
MethodTryGet<T>(ref T)
Inherited from IPageCapabilities.TryGet<T>.
Parameters
capability- The implementation, when this render offers the capability.
Returns
MethodAttachLifetime(Pages.RenderLifetime lifetime)
Parameters
lifetime- The render lifetime to attach.
MethodAttachDeadline(CancellationToken deadline)
Parameters
deadline- The deadline's token.
MethodAbandon()
Pages.PageCatalogScope
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.
MethodPageCatalogScope(PagePath, IReadOnlyList<ShellLink>, Pages.IPageReadStore, Pages.PageReadOptions, Pages.ReadBudget, Pages.ReservedPaths, PageContentTypes, Pages.PageSeeds, string)
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.
MethodShellLinks()
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
Exceptions
InvalidOperationException- The render was abandoned.
MethodListAsync(string)
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/blogare the same request. A prefix lists the key itself and the keys beneath it, never a key that merely starts with the same text:/bloglists/blogand/blog/post, never/blogroll.
Returns
Exceptions
ArgumentException-
The prefix cannot name a key, for example one containing
?or#. InvalidOperationException- The render was abandoned, or the prefix holds more rows than the host's listing cap; the message names the cap and suggests a prefix.
MethodReadAsync(string)
Inherited from IPageCatalog.ReadAsync.
Parameters
key- The page's key; normalised before it is read.
Returns
null when no
live page has that key. A tombstone is listed as deleted, and reads as absent.
Exceptions
ArgumentException- The key cannot name a page.
InvalidOperationException- The render was abandoned, or the source would take the render past its source allowance.
MethodRevisionsAsync(string)
Inherited from IPageCatalog.RevisionsAsync.
Parameters
key- The page's key; normalised before it is read.
Returns
Exceptions
ArgumentException- The key cannot name a page.
InvalidOperationException- The render was abandoned.
MethodReadRevisionAsync(string, string)
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
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
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.
MethodPageChain(Pages.PageEnvironment environment, Editor.PageEditor editor, ILoggerFactory loggerFactory, PageRequest request, PageUser user, Pages.PageSessionRequest session, bool isHead, Pages.BodyBudget bodyBudget, Pages.IPageBodySink bodySink, Pages.RenderFetchBudget fetchBudget, Pages.ReadBudget readBudget, IReadOnlyDictionary<string, string> assets, IReadOnlyList<ShellLink> shellLinks, string loginRedirect, Func<string> antiforgeryField, Pages.PageRenderer.RenderSession render, CancellationToken aborted)
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
null.MethodIsReserved(PagePath key)
Parameters
key- The canonical key.
MethodCreateLayer(PagePath key, Pages.PageLayerRole role, PageRequest request, Pages.BodyBudget budget, IReadOnlyList<Pages.PageRenderIdentity> path, int depth, PageCapture content)
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)
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
MethodComposeAsync(PagePath key, PageRequest request, IReadOnlyList<Pages.PageRenderIdentity> path, int depth)
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
MethodPageChainFailureException(int statusCode, Errors.ErrorMessage error)
Parameters
statusCode- The status the top-level page would answer with.
error- What to tell the reader.
PropertyStatusCode
PropertyError
Pages.PageChainResult
Pages.PageChainResult.Failed
MethodFailed(int StatusCode, Errors.ErrorMessage Error)
Parameters
StatusCode- The status to send.
Error- What to tell the reader.
PropertyStatusCode
PropertyError
Pages.PageChainResult.Served
MethodServed(PageResponse Response, string Body)
Parameters
Response- The response the content owns, with every layer's script permission.
Body- The outermost layer's body.
PropertyResponse
PropertyBody
Pages.PageCommitState
PropertyCommitted
Pages.PageCompositionScope
MethodPageCompositionScope(Pages.PageChain, Pages.PageCompositionState, PageRequest, IReadOnlyList<Pages.PageRenderIdentity>, int, PagePath, Func<Pages.SimpleResponse>)
MethodEmbedAsync(string, PageRequest)
Inherited from IPageComposition.EmbedAsync.
Parameters
key- The embedded page's canonical key, such as
/cards/post. request- The request to run it against, or
nullfor this page's.
Returns
Exceptions
ArgumentException- The key is not a page address.
InvalidOperationException- The page is already being rendered in this chain with the same request, or the render's depth or fan-out limit has been reached.
- The key names no page, or one that cannot be served; the embedded page redirects; or its wrapper cannot be served.
OperationCanceledException- The render's deadline fired while it ran.
MethodCaptureAsync(string, PageRequest)
Inherited from IPageComposition.CaptureAsync.
Parameters
key- The captured page's canonical key.
request- The request to run it against, or
nullfor this page's.
Returns
Exceptions
ArgumentException- The key is not a page address.
InvalidOperationException- The page is already being rendered in this chain with the same request, or the render's depth or fan-out limit has been reached.
- The key names no page, or one that cannot be served; the captured page redirects; or its wrapper cannot be served.
OperationCanceledException- The render's deadline fired while it ran.
MethodWrap(string, PageRequest)
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
nullfor this page's.
Exceptions
ArgumentException- The key is not a page address.
InvalidOperationException- The key is a reserved path, or the response has already been flushed.
MethodWrap()
Inherited from IPageComposition.Wrap.
Exceptions
InvalidOperationException- The response has already been flushed.
Pages.PageCompositionState
return; from a guard is still wrapped. Each call adds a layer outside the last.
PropertyWraps
PropertyIsEmpty
MethodWrap(PagePath key, PageRequest request, bool isDefault)
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
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)
Parameters
database- The store to repair.
cancellationToken- Cancels the repair.
Returns
Pages.PageContentTypesConfiguration
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)
Parameters
configuration- The application configuration.
logger- Where the map is reported once.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:ContentTypes into the caller's report.Parameters
reader- A reader opened on
Pages:ContentTypes, which the caller completes.
MethodLog(ILogger logger, PageContentTypes contentTypes)
Parameters
logger- Where the map is reported once.
contentTypes- The map that was read.
Pages.PageCredential
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)
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
PropertyHost
PropertyHeader
PropertyPage
PropertyIncludesDescendants
PropertyScope
PropertyHeaderValue
MethodAppliesTo(Uri uri)
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)
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()
Returns
Pages.PageDiagnostics
MethodToSdk(IEnumerable<PageDiagnostic> diagnostics)
Parameters
diagnostics- The compiler's diagnostics.
MethodToSdk(PageDiagnostic diagnostic)
Parameters
diagnostic- The compiler's diagnostic.
Pages.PageEditorOptions
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
MethodFromConfiguration(IConfiguration configuration)
Pages:Editor.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Editor into the caller's report.Parameters
reader- A reader opened on
Pages:Editor, which the caller completes.
Pages.PageEndpoint
MethodPageEndpoint()
Pages.PageEnvironment
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)
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
nullwhen this host offers none. A host without one simply does not offer the capability, which is what a page is already prepared for.
PropertyReserved
PropertyEditor
PropertyLayout
PropertyRender
PropertyContentTypes
PropertyStorage
PropertyFetch
PropertyRead
PropertyStateStore
PropertyReadStore
PropertySeeds
PropertySaver
PropertyFetcher
PropertyMetrics
PropertyAntiforgery
PropertyMarkdown
IMarkdownRenderer.PropertyDiff
IDiffRenderer.PropertySessions
PropertySessionStore
PropertySessionCookie
PropertyJobs
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
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)
Parameters
name- The header name.
Returns
true for a listed name or an X- name.MethodIsResponseAllowed(string name)
Parameters
name- The header name.
Returns
true for a listed name or an X- name.Pages.PageFetchOptions
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
Pages:Fetch:Credentials accepts.PropertyTimeoutSeconds
PropertyMaxResponseBytes
PropertyStreamSilenceSeconds
PropertyStreamMaxSeconds
PropertyMaxStreamBytes
PropertyMaxRequestsPerRender
PropertyMaxRedirects
PropertyCredentials
PropertyTimeout
PropertyStreamSilence
PropertyStreamMax
MethodFromConfiguration(IConfiguration configuration)
Pages:Fetch.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Fetch into the caller's report.Parameters
reader- A reader opened on
Pages:Fetch, which the caller completes.
Pages.PageFetcher
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>)
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)
Inherited from Pages.IPageFetcher.FetchAsync.
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
MethodStreamAsync(HttpFetchRequest, string, CancellationToken, CancellationToken)
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
Pages.PageHead
PropertySeedHash
PropertyContentHash
Pages.PageHeadSummary
MethodPageHeadSummary(PagePath Path, bool IsDeleted, string SeedHash, string ContentHash)
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
PropertyIsDeleted
PropertySeedHash
PropertyContentHash
Pages.PageHealth
MethodPageHealth(int)
PropertyLimit
PropertyAbandoned
MethodRegister()
MethodRelease()
Pages.PageHttpFetch
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)
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)
Inherited from IHttpFetch.SendAsync.
Parameters
request- The request to make.
Returns
MethodStreamAsync(HttpFetchRequest)
Inherited from IHttpFetch.StreamAsync.
Parameters
request- The request to make.
Returns
MethodAttachLifetime(Pages.RenderLifetime)
Inherited from Pages.IRenderLifetimeAware.AttachLifetime.
Parameters
lifetime- The render lifetime that owns this capability.
Pages.PageImage
MethodPageImage(string TemplateHash, string RuntimeId, byte[] Bytes, byte[] Symbols, IReadOnlyList<PageDiagnostic> Diagnostics, PageKind? Kind, string Libraries)
Parameters
TemplateHash- The fingerprint of the template the image was built from.
RuntimeId- The build that produced the image.
Bytes- The emitted assembly, or
nullwhen compilation failed or there was nothing to compile. Symbols- The emitted portable PDB, or
nullwhen 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
nullwhen 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
nullwhen it named none. A page whose closure has moved is compiled again before it runs.
PropertyTemplateHash
PropertyRuntimeId
PropertyBytes
null when compilation failed or there was nothing to compile.PropertySymbols
null when compilation failed.PropertyDiagnostics
PropertyKind
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
null when
it named none. A page whose closure has moved is compiled again before it runs.
MethodIsCurrent(string templateHash, string runtimeId, string 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
nullwhen the page named none.
Pages.PageImageBuilder
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>)
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
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
FieldNotCompiled
FieldStale
FieldCompileFailed
FieldCompiledWithWarnings
FieldCompiled
FieldLibrary
FieldLibraryWithIssues
FieldWorker
FieldWorkerWithWarnings
Pages.PageImageStatus
MethodDescribe(string runtimeId, bool hasImage, bool hasDiagnostics, string currentRuntimeId, PageKind? kind)
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
MethodDescribe(Pages.PageImageState state)
Parameters
state- The state to describe.
Returns
MethodClass(Pages.PageImageState state)
Parameters
state- The state to name.
Returns
Pages.PageJobEnvironment
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)
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
PropertyStore
PropertyState
PropertyStorage
PropertyFetcher
PropertyFetch
PropertyReadStore
PropertySeeds
PropertyRead
PropertyReserved
PropertyContentTypes
PropertyImages
PropertyLibraries
PropertyCompiler
PropertyMetrics
Pages.PageJobOptions
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
PropertyMaxConcurrent
PropertySilenceSeconds
PropertyMaxDurationSeconds
PropertyMaxEvents
PropertyMaxEventBytes
PropertyRetentionMinutes
PropertyMaxWaitSeconds
PropertyMaxMessageBytes
PropertyMaxPendingMessages
PropertySilence
PropertyMaxDuration
PropertyRetention
PropertyMaxWait
MethodFromConfiguration(IConfiguration configuration)
Pages:Jobs.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Jobs into the caller's report.Parameters
reader- A reader opened on
Pages:Jobs, which the caller completes.
Pages.PageJobsScope
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)
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)
workerKey.Inherited from IPageJobs.StartAsync.
Parameters
workerKey- The canonical key of a stored worker.
firstMessage-
The first message the worker receives, or
nullwhen it needs none. Bounded byPages:Jobs:MaxMessageBytes.
Returns
MethodSendAsync(string, string)
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
MethodGetAsync(string)
Inherited from IPageJobs.GetAsync.
Parameters
jobId- The id a start or a listing answered with.
Returns
null when it is unknown or another visitor's.MethodListAsync()
Inherited from IPageJobs.ListAsync.
Returns
MethodReadEventsAsync(string, long, double?)
Inherited from IPageJobs.ReadEventsAsync.
Parameters
jobId- The id a start or a listing answered with.
after- The last sequence the caller has already seen;
0reads from the start. waitSeconds-
How long to wait for an event that has not arrived yet, capped by
Pages:Jobs:MaxWaitSecondsand by the render's own budget. Omitted ornulldoes not wait.
Returns
after, or a reset when the journal no longer holds that
sequence, with the job's state once it has ended.
MethodCancelAsync(string)
Inherited from IPageJobs.CancelAsync.
Parameters
jobId- The id a start or a listing answered with.
Returns
Pages.PageLayer
MethodPageLayer(Pages.SimpleContext Context, Pages.PageLayoutState Layout, Pages.PageCompositionState Composition, IReadOnlyList<Pages.PageRenderIdentity> Path, int Depth)
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
PropertyLayout
PropertyComposition
PropertyPath
PropertyDepth
Pages.PageLayerRole
FieldContent
FieldLayout
FieldEmbedded
Pages.PageLayoutOptions
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
null when there is none.MethodFromConfiguration(IConfiguration configuration)
Pages:Layout.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Layout into the caller's report.Parameters
reader- A reader opened on
Pages:Layout, which the caller completes.
Pages.PageLayoutState
PropertyContent
null otherwise.Inherited from IPageLayout.Content.
PropertyTitle
null until it is set.Inherited from IPageLayout.Title.
Exceptions
ArgumentException- The title is blank.
PropertyStylesheets
MethodAddHead(string)
head.Inherited from IPageLayout.AddHead.
Parameters
markup- The markup to add; it is the caller's, not a request value.
MethodAddStylesheet(string)
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
MethodPageLibraries(Pages.IPageReadStore)
MethodHeadsAsync(CancellationToken)
MethodLiveAsync(CancellationToken)
Pages.PageLibrary
MethodPageLibrary(PagePath Key, string Hash, string Template)
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
PropertyHash
PropertyTemplate
Pages.PageLibraryFingerprint
MethodOf(IEnumerable<ValueTuple<string, string>> libraries)
key@hash per library, in ordinal key order.Parameters
libraries- The keys and the revision hashes they were compiled from.
Returns
Pages.PageLibraryHead
MethodPageLibraryHead(PagePath Key, string Hash)
Parameters
Key- The library's canonical key.
Hash- The head revision's hash.
PropertyKey
PropertyHash
Pages.PageListing
MethodPageListing(PagePath Path, bool IsDeleted, Pages.PageImageState State)
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
PropertyIsDeleted
PropertyState
Pages.PageMetrics
FieldMeterName
PropertyInstruments
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
FieldStreamBuckets
page.stream.duration, in seconds.FieldImageBuckets
page.image.size, in bytes.FieldRenderOk
FieldRenderCompileError
FieldRenderError
FieldRenderNotFound
FieldNotFoundPath
FieldRenderTimeout
FieldStreamCeiling
FieldStreamSilence
FieldStreamCompleted
FieldStreamClientLeft
FieldStreamError
FieldAssetServed
FieldAssetNotModified
304 Not Modified.FieldAssetUnknown
FieldAssetNonAsset
FieldCacheHit
FieldCacheMiss
FieldCacheNone
FieldReasonImport
FieldImportCommitted
FieldImportFailed
FieldImportAborted
FieldFetchOk
FieldFetchHttpError
FieldFetchTimeout
FieldFetchNetwork
FieldFetchInvalid
FieldFetchLimit
FieldFetchRedirectLimit
FieldFetchAborted
FieldStaleLibraryChanged
MethodRecordStream(PagePath path, string outcome, TimeSpan duration)
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)
Parameters
duration- How long the request waited.
MethodRecordLayoutFallback(PagePath path)
Parameters
path- The page that was served instead.
MethodRecordRecursiveComposition(PagePath path)
Parameters
path- The page that was composed again.
MethodRecordAbandoned(PagePath path)
Parameters
path- The page that outran its budget.
MethodRecordAsset(string outcome)
Parameters
outcome- One of AssetServed, AssetNotModified, AssetUnknown or AssetNonAsset.
MethodRecordFetch(PagePath path, string outcome, TimeSpan duration)
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)
Parameters
outcome- One of ImportCommitted, ImportFailed or ImportAborted.
duration- How long compiling and committing the batch took.
Pages.PageReadHead
MethodPageReadHead(string Key, DateTimeOffset SavedAt, string Hash, bool IsDeleted, PageKind? TemplateKind, string RuntimeId, bool HasImage, bool HasDiagnostics, string SeedHash, string ContentHash)
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
nullwhen it has never been judged. RuntimeId- The build that compiled the head, or
nullwhen 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
PropertySavedAt
PropertyHash
PropertyIsDeleted
PropertyTemplateKind
null when it has never been judged.
PropertyRuntimeId
null when it has no image.PropertyHasImage
PropertyHasDiagnostics
PropertySeedHash
PropertyContentHash
Pages.PageReadOptions
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
FieldMinimumSourceCharsPerRender
PropertyMaxRowsPerList
PropertyMaxSourceCharsPerRender
MethodFromConfiguration(IConfiguration configuration)
Pages:Read.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Read into the caller's report.Parameters
reader- A reader opened on
Pages:Read, which the caller completes.
Pages.PageReadRevision
MethodPageReadRevision(string Hash, DateTimeOffset SavedAt, bool IsCurrent)
Parameters
Hash- The revision's hash.
SavedAt- When the revision was saved.
IsCurrent- Whether the live head points at this revision.
PropertyHash
PropertySavedAt
PropertyIsCurrent
Pages.PageReadSource
MethodPageReadSource(string Key, string Hash, DateTimeOffset SavedAt, string Template)
Parameters
Key- The page's canonical key.
Hash- The revision's hash.
SavedAt- When the revision was saved.
Template- The stored template text.
PropertyKey
PropertyHash
PropertySavedAt
PropertyTemplate
Pages.PageRenderIdentity
MethodPageRenderIdentity(string Key, string Query)
Parameters
Key- The page's canonical key.
Query- The fingerprint of the request's query.
PropertyKey
PropertyQuery
MethodOf(PagePath key, PageRequest request)
Parameters
key- The page's canonical key.
request- The request it runs against.
Pages.PageRenderer
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>)
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)
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)
Parameters
path- The canonical key to read.
cancellationToken- Cancels the read.
MethodGetRevisionByHashAsync(string hash, CancellationToken cancellationToken)
Parameters
hash- The revision's stored hash.
cancellationToken- Cancels the read.
MethodRenderAsync(PagePath path, Pages.SimpleContext context, Pages.PageSelection selection, CancellationToken cancellationToken)
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)
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
Pages.PageRenderer.RenderSession
PropertyIsStreaming
PropertyStreamOutcome
MethodComplete(bool clientLeft)
Parameters
clientLeft- Whether the request was aborted.
MethodFail()
MethodTruncated()
PropertyTokenCancelled
MethodRenderAsync(PagePath path, Pages.SimpleContext context, Pages.PageSelection selection)
Parameters
path- The layer's canonical key.
context- The context the layer writes to.
selection- Which representation to render, or
nullfor the page's own.
MethodDisposeAsync()
Inherited from IAsyncDisposable.DisposeAsync.
Pages.PageRequestSnapshot
MethodCreate(HttpRequest request)
Parameters
request- The request to read.
Returns
Pages.PageResponseState
MethodPageResponseState(string contentType)
Parameters
contentType- The media type the page's key names.
PropertyContentType
PropertyLocation
null when the page did not redirect.MethodSetStatus(int status)
Parameters
status- The code to send, between 100 and 599.
MethodSetContentType(string contentType)
Parameters
contentType- The media type to send.
MethodSetHeader(string name, string value)
Parameters
name- The header name.
value- The header value; it may not contain a line break.
Exceptions
ArgumentException- The header is reserved to the shell, or the value cannot be sent safely.
MethodAllowScripts()
MethodRedirect(string location, int status)
Parameters
location- The target, relative or absolute.
status- The redirect status; 302 by default.
MethodToResponse()
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
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)
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
MethodAllowsBody(PageResponse response)
Parameters
response- What the page asked the response to be.
Pages.PageRevision
Pages.PageRevisionSummary
MethodPageRevisionSummary(string, DateTimeOffset, string, Pages.PageImageState, bool)
Pages.PageRevisionTemplate
MethodPageRevisionTemplate(PagePath, string, DateTimeOffset, string, Pages.PageImageState, string)
Pages.PageSeedInstaller
MethodPlanAsync(Editor.PageEditor pages, Pages.PageSeeds seeds, CancellationToken cancellationToken)
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)
Parameters
pages- The page store.
seed- The plan entry to write.
cancellationToken- Cancels the write.
Pages.PageSeedInstaller.SeedOutcome
Pages.PageSeedInstaller.SeedPlan
MethodSeedPlan(PagePath Path, string Source, string SeedHash, PageSeedSummary Summary, bool HoldsSeed)
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
PropertySource
PropertySeedHash
PropertySummary
PropertyHoldsSeed
Pages.PageSeedInstaller.SeedResult
MethodSeedResult(PagePath Path, PageSeedSummary Was, Pages.PageSeedInstaller.SeedOutcome Outcome, string Hash)
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
PropertyWas
PropertyOutcome
PropertyHash
Pages.PageSeeds
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)
Parameters
directory- The folder the build copies the seed files into.
Exceptions
ArgumentException- The folder is blank.
PropertyFiles
PropertyPaths
MethodContains(PagePath path)
Parameters
path- The canonical key.
MethodFind(PagePath path)
Parameters
path- The canonical key.
MethodSource(PagePath path)
Parameters
path- The canonical key.
Pages.PageSelection
MethodPageSelection(Pages.PageTemplate Page, bool IsHistorical)
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
PropertyIsHistorical
?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
MethodPageSessionCaps(int MaxValueBytes, int MaxKeys, int MaxTotalBytes)
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
PropertyMaxKeys
PropertyMaxTotalBytes
PropertyAnonymous
PropertySignedIn
Pages.PageSessionCleanupService
MethodPageSessionCleanupService(Pages.IPageSessionStore, ILogger<Pages.PageSessionCleanupService>)
Pages.PageSessionEntry
null for an anonymous
visitor.
PropertyAccount
null for an anonymous visitor.PropertyCreatedAt
PropertyUpdatedAt
Pages.PageSessionOptions
Pages:Session, and the key length is Pages:Storage:MaxKeyChars, the same rule
page state uses.
PropertyMaxKeyChars
PropertyAnonymous
PropertySignedIn
PropertyAnonymousIdle
PropertySignedInIdle
PropertyMaxLiveSessions
PropertyCommandTimeoutSeconds
PropertyCommandTimeout
MethodFor(string account)
account.Parameters
account- The normalised account name, or
null.
MethodIdleFor(string account)
account survives without a visit.Parameters
account- The normalised account name, or
null.
MethodFromConfiguration(IConfiguration configuration)
Pages:Session.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Session into the caller's report.Parameters
reader- A reader opened on
Pages:Session, which the caller completes.
Pages.PageSessionRequest
MethodPageSessionRequest(string, string, bool, bool)
PropertyId
PropertyAccount
null.PropertyPresented
PropertyExists
PropertyMinted
PropertyNeedsCookie
MethodEnsureAsync(Pages.IPageSessionStore store, CancellationToken cancellationToken)
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)
Parameters
store- Where the row lives.
cancellationToken- Cancels the work.
MethodGetStringAsync(Pages.IPageSessionStore store, string pagePath, string key, CancellationToken cancellationToken)
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
null when the key is absent.MethodSetTextAsync(Pages.IPageSessionStore store, Pages.PageSessionOptions options, string pagePath, string key, string text, CancellationToken cancellationToken)
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)
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
Pages.PageSessionResolver
MethodResolveAsync(HttpContext context, Pages.IPageSessionStore store, Authentication.PageSessionCookieOptions options, PageUser user, CancellationToken cancellationToken)
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
Pages.PageSessionScope
MethodPageSessionScope(PagePath, Pages.IPageSessionStore, Pages.PageSessionOptions, Pages.PageSessionRequest, bool, bool, Pages.PageCommitState)
MethodTryGetValueAsync<T>(string)
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
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)
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
Exceptions
ArgumentException- The path cannot name a page.
JsonException- The stored value does not deserialise as
T.
MethodSetAsync<T>(string, T)
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
Exceptions
ArgumentException- The key or the value breaks a cap.
InvalidOperationException- A layout or a
HEADrender tried to write.
MethodDeleteAsync(string)
Inherited from IPageSession.DeleteAsync.
Parameters
key- The key to remove.
Returns
Exceptions
InvalidOperationException- A layout or a
HEADrender tried to write.
MethodKeysAsync()
Inherited from IPageSession.KeysAsync.
Returns
MethodAllKeysAsync()
Inherited from IPageSession.AllKeysAsync.
Returns
Pages.PageSessionSweep
MethodPageSessionSweep(int Expired, int AnonymousEvicted, int SignedInEvicted)
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
PropertyAnonymousEvicted
PropertySignedInEvicted
Pages.PageSessionValueEntry
PropertyValue
null is the text null, not a missing row.Pages.PageStateEntry
PropertyValue
null is the text null, not a missing row.PropertyUpdatedAt
Pages.PageStateKey
MethodIsValid(string key, int maxChars)
key may name a state value.Parameters
key- The key to test.
maxChars- The configured maximum length.
MethodValidate(string key, int maxChars)
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
MethodPageStateValue(string Key, string Value)
Parameters
Key- The key, 1–MaxKeyChars characters, no control characters.
Value- The value as JSON. A stored
nullis the textnull, not a missing row.
PropertyKey
PropertyValue
null is the text null, not a missing row.Pages.PageStorageOptions
Pages:Storage, and MaxPageBytes must be at least
MaxValueBytes so a single value at the per-value limit still fits an empty page.
PropertyMaxKeyChars
PropertyMaxValueBytes
PropertyMaxKeysPerPage
PropertyMaxPageBytes
PropertyCommandTimeoutSeconds
PropertyCommandTimeout
MethodFromConfiguration(IConfiguration configuration)
Pages:Storage.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Storage into the caller's report.Parameters
reader- A reader opened on
Pages:Storage, which the caller completes.
Pages.PageStorageScope
MethodPageStorageScope(PagePath, Pages.IPageStateStore, Pages.PageStorageOptions, bool)
MethodTryGetValueAsync<T>(string)
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:MaxKeyCharscharacters, no control characters.
Returns
null is found with a null value, which is how a
deliberately null value is told apart from an absent one. The test and the read are one
operation, so they cannot race.
Exceptions
JsonException- The stored value does not deserialise as
T.
MethodSetAsync<T>(string, T)
Inherited from IPageStorage.SetAsync<T>.
Type parameters
T- The type to serialise.
Parameters
key- The key; ordinal, 1 to
Pages:Storage:MaxKeyCharscharacters, no control characters. value- The value; a null is stored as JSON
null.
Returns
Exceptions
ArgumentException- The key or the value breaks a cap.
MethodDeleteAsync(string)
Inherited from IPageStorage.DeleteAsync.
Parameters
key- The key to remove.
Returns
MethodKeysAsync()
Inherited from IPageStorage.KeysAsync.
Returns
Pages.PageTemplate
MethodPageTemplate(PagePath Path, string Template, Pages.PageImage Image)
Parameters
Path- The canonical key the page is stored under.
Template- The template text.
Image-
The image built from the template, or
nullwhen this build has never compiled it. A template without one is compiled on its next request.
PropertyKind
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
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)
Parameters
path- The canonical key the page is saved under.
source- The template text.
image- The compiled image, or
nullwhen there is none. runtimeId- The build that compiled the image.
seedHash-
The seed this write is installing, or
nullwhen 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
Pages.PageWrap
MethodPageWrap(PagePath Key, PageRequest Request, bool IsDefault)
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
PropertyRequest
PropertyIsDefault
Pages.PageWriteAction
PropertyHasActed
MethodAct()
Pages.PageWritesScope
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 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)
Inherited from IPageWrites.Resolve.
Parameters
key- The text the page was given.
Returns
MethodSeedSourceAsync(string)
Inherited from IPageWrites.SeedSourceAsync.
Parameters
key- The page's key; normalised before it is read.
Returns
null when the release ships no seed for that key.Exceptions
ArgumentException- The key cannot name a page.
MethodSaveAsync(string)
Inherited from IPageWrites.SaveAsync.
Parameters
template- The template text. It may be empty; an empty page is a page.
Returns
Exceptions
ArgumentNullException- The template is
null. - This render has no signed-in visitor, so nothing was saved.
InvalidOperationException-
The request is a
HEAD, the render was abandoned or its deadline passed before the save started, or this render has already written.
MethodSaveAsync(string, string, string)
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
nullwhen the page had no live source: a new page, or a tombstone. A null expectation is refused as Stale if the page exists by the time the save runs, so a create cannot quietly overwrite one.
Exceptions
- This render has no signed-in visitor, so nothing was saved.
InvalidOperationException- A reserved key, a
HEAD, an ended render or a second write.
MethodDeleteAsync(string)
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)
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
Exceptions
- This render has no signed-in visitor.
InvalidOperationException- A reserved key, a
HEAD, an ended render or a second write.
MethodAdoptSeedAsync(string)
Inherited from IPageWrites.AdoptSeedAsync.
Parameters
key- The page's key; normalised and checked.
Returns
Exceptions
- This render has no signed-in visitor.
InvalidOperationException- A reserved key, a
HEAD, an ended render, a second write, or content that is not the seed.
MethodInstallSeedAsync(string, string)
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
Exceptions
- This render has no signed-in visitor.
InvalidOperationException- A reserved key, a
HEAD, an ended render or a second write.
Pages.ReadBudget
MethodReadBudget(int maxChars)
Parameters
maxChars- How much template one render may pull in.
PropertyMaxChars
MethodTryCharge(int chars)
Parameters
chars- The template's length.
Returns
Pages.RenderBoundCapability
PropertyIsAbandoned
PropertyDeadline
MethodAttachDeadline(CancellationToken)
Inherited from Pages.IRenderBoundCapability.AttachDeadline.
Parameters
deadline- The deadline's token; it outlives this use of it.
MethodAbandon()
Inherited from Pages.IRenderBoundCapability.Abandon.
Pages.RenderFetchBudget
MethodRenderFetchBudget(int maxRequests)
Parameters
maxRequests- How many requests the whole render may make.
MethodTryTake()
Returns
true when the caller may make the request.Pages.RenderLifetime
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)
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
PropertyIsStreaming
PropertyOutcome
completed while it is still running.MethodOnCommit(Action onCommit)
Parameters
onCommit- The callback; it runs once, before the response starts.
MethodRegisterCleanup(Func<Task> cleanup)
Parameters
cleanup- The cleanup operation to await when the render ends.
MethodBeginStreamAsync()
Returns
Exceptions
MethodReArm()
MethodComplete(bool clientLeft)
Parameters
clientLeft- Whether the request was aborted rather than the page returning.
MethodFail()
MethodTruncated()
MethodAbandon(bool clientLeft)
Parameters
clientLeft- Whether the visitor left rather than the deadline firing.
MethodDisposeAsync()
MethodDisposeDeadline()
Pages.RenderOptions
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
FieldMaximumEmbedDepth
PropertyTimeoutSeconds
PropertySlots
PropertyMaxBodyChars
PropertyAbandonedLimit
PropertyMaxLayoutDepth
PropertyMaxEmbedDepth
PropertyMaxEmbeds
PropertyTimeout
MethodFromConfiguration(IConfiguration configuration)
Pages:Render.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Render into the caller's report.Parameters
reader- A reader opened on
Pages:Render, which the caller completes.
Pages.RenderResult
MethodRenderResult(Pages.RenderStatus Status, IReadOnlyList<PageDiagnostic> Diagnostics)
Parameters
Status- What rendering did.
Diagnostics-
The compiler's author-facing diagnostics when
Statusis CompileFailed; empty otherwise.
PropertyStatus
PropertyDiagnostics
Status is
CompileFailed; empty otherwise.
PropertyIsSource
PropertyNotFound
PropertyRendered
PropertyFromSource
PropertyTimedOut
MethodCompileFailed(IReadOnlyList<PageDiagnostic> diagnostics)
Parameters
diagnostics- The compiler's author-facing diagnostics.
Pages.RenderStatus
FieldRendered
FieldCompileFailed
FieldNotFound
FieldTimeout
Pages.ReservedPaths
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
MethodReservedPaths(IEnumerable<string> paths)
Parameters
paths- The configured keys, which must hold at least one.
Exceptions
ArgumentException- No key was given, so no route would be reserved.
PropertyKeys
MethodIsReserved(PagePath path)
Parameters
path- The canonical key to test.
MethodMatchingPrefix(PagePath path)
/admin/scrub names that route rather than
the /admin root above it.
Parameters
path- The canonical key to test.
Pages.SeedCommands
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
MethodIsCommand(string[] args)
Parameters
args- The process arguments.
MethodRunAsync(string[] args, IServiceProvider services, Stream output, TextWriter error, CancellationToken cancellationToken)
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
Pages.SeedFile
MethodSeedFile(PagePath Path, string Name, string Source, string 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
PropertyName
/ separators.PropertySource
PropertyHash
Source, which is what a seed write records.Pages.SeedVerdictWords
MethodDescribe(SeedComparison comparison, string shipped)
Parameters
comparison- The comparison of R, S and H.
shipped- The hash this release ships, or null when it ships none.
MethodNew()
MethodDeleted()
Pages.SimpleContext
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
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)
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
nullfor an anonymous visitor. loginRedirect- Where RedirectToLogin sends an anonymous visitor.
antiforgeryField-
Builds the hidden antiforgery input, or
nullwhen 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
nullwhen 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
nullwhen it cannot stream. wouldWrap- Whether a response of this content type would be wrapped in a layout, in which case it cannot stream.
PropertyEditorPath
Inherited from IContext.EditorPath.
Pages:Editor:Key — so a page that hard-codes it
breaks when the owner moves the editor. The editor's own page is served at this key and takes
the page to edit as ?edit=, which makes
ctx.EditorPath + "?edit=" + System.Uri.EscapeDataString(ctx.Path) the way to offer
"edit this page".
PropertyUser
null for an anonymous visitor.Inherited from IContext.User.
if (ctx.User is not { } user) { ctx.Response.RedirectToLogin(); return; }.
PropertyAborted
Inherited from IContext.Aborted.
PropertyCapabilities
Inherited from IContext.Capabilities.
null; a page decides whether
that is fatal with Get<T> or
GetRequired<T>.
MethodAttachLifetime(Pages.RenderLifetime lifetime)
Parameters
lifetime- The lifetime the renderer opened for this request.
MethodAbandon()
MethodLog(string)
Inherited from IContext.Log.
Parameters
message- The message to log.
MethodLogWarning(string)
Inherited from IContext.LogWarning.
Parameters
message- The message to log.
MethodLogError(string)
Inherited from IContext.LogError.
Parameters
message- The message to log.
MethodAssetUrl(string)
Inherited from IContext.AssetUrl.
Parameters
href- The link as the page would write it.
Returns
?v= hash, or the link unchanged when it is not a bare site-relative
path or does not name a live asset. A query or fragment, an absolute or protocol-relative URL
and a missing, deleted or compiled page all keep the link as written, so an unversioned
fallback still works.
Pages.SimpleResponse
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)
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
nullwhen 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()
MethodGetBody()
PropertyIsCommitted
MethodCompleteAsync()
MethodAttachLifetime(Pages.RenderLifetime lifetime)
Parameters
lifetime- The lifetime the renderer opened for this request.
MethodAbandon()
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)
Inherited from IPageResponse.SetStatus.
Parameters
status- The code to send, between 100 and 599.
MethodSetContentType(string)
Inherited from IPageResponse.SetContentType.
Parameters
contentType- The media type to send.
MethodSetHeader(string, string)
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()
Inherited from IPageResponse.AllowScripts.
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.
MethodRedirectToLogin()
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
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
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)
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)
Inherited from Pages.IPageBatchStore.SaveBatchAsync.
Parameters
pages- The pages to store, in key order.
cancellationToken- Cancels the write.
Returns
MethodWriteStateAsync(Storage.StorageDbContext database, PagePath path, Pages.PageStateValue value, DateTimeOffset updatedAt, CancellationToken cancellationToken)
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
Pages.SqlitePageReadStore
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>)
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)
Inherited from Pages.IPageReadStore.ListLibrariesAsync.
Parameters
cancellationToken- Cancels the read.
Returns
MethodListAsync(string, int, CancellationToken)
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
limit heads, in ordinal key order.MethodGetHeadAsync(string, CancellationToken)
Inherited from Pages.IPageReadStore.GetHeadAsync.
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no page has that key.MethodGetSourceAsync(string, CancellationToken)
Inherited from Pages.IPageReadStore.GetSourceAsync.
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
null when no live page has that key.MethodListRevisionsAsync(string, CancellationToken)
Inherited from Pages.IPageReadStore.ListRevisionsAsync.
Parameters
key- The canonical key to read.
cancellationToken- Cancels the read.
Returns
MethodGetRevisionSourceAsync(string, string, CancellationToken)
Inherited from Pages.IPageReadStore.GetRevisionSourceAsync.
Parameters
key- The canonical key the revision belongs to.
hash- The revision's hash.
cancellationToken- Cancels the read.
Returns
null when that page has no such revision.Pages.SqlitePageRevisionStore
MethodSqlitePageRevisionStore(IDbContextFactory<Storage.StorageDbContext>, ILogger<Pages.SqlitePageRevisionStore>)
MethodSaveAsync(Pages.PageTemplate, CancellationToken)
Inherited from Pages.IPageRevisionStore.SaveAsync.
Parameters
revision- The revision, already built with its id, hash and image.
cancellationToken- Cancels the write.
Returns
MethodTrySaveAsync(Pages.PageTemplate, string, CancellationToken)
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
MethodSqlitePageSessionStore(IDbContextFactory<Storage.StorageDbContext>, Pages.PageSessionOptions, TimeProvider)
MethodFindAsync(string, CancellationToken)
Inherited from Pages.IPageSessionStore.FindAsync.
Parameters
sessionId- The id from the visitor's cookie.
cancellationToken- Cancels the read.
Returns
null when the id names no live session.MethodEnsureAsync(string, string, CancellationToken)
Inherited from Pages.IPageSessionStore.EnsureAsync.
Parameters
sessionId- The id to mint.
account- The normalised account name, or
null. cancellationToken- Cancels the write.
Returns
MethodTouchAsync(string, CancellationToken)
Inherited from Pages.IPageSessionStore.TouchAsync.
Parameters
sessionId- The id that was touched.
cancellationToken- Cancels the write.
MethodDeleteAsync(string, CancellationToken)
Inherited from Pages.IPageSessionStore.DeleteAsync.
Parameters
sessionId- The id to delete.
cancellationToken- Cancels the write.
Returns
MethodGetValueAsync(string, string, string, CancellationToken)
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
null when the key is absent.MethodSetValueAsync(string, string, string, string, Pages.PageSessionCaps, CancellationToken)
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)
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
MethodListKeysAsync(string, string, CancellationToken)
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
MethodListAllKeysAsync(string, CancellationToken)
Inherited from Pages.IPageSessionStore.ListAllKeysAsync.
Parameters
sessionId- The visitor's session.
cancellationToken- Cancels the read.
Returns
MethodRemoveExpiredAsync(CancellationToken)
Inherited from Pages.IPageSessionStore.RemoveExpiredAsync.
Parameters
cancellationToken- Cancels the sweep.
Returns
MethodUpsertAsync(Storage.StorageDbContext, string, string, string, string, Pages.PageSessionCaps, CancellationToken)
Returns
Pages.SqlitePageStateStore
MethodSqlitePageStateStore(IDbContextFactory<Storage.StorageDbContext>, Pages.PageStorageOptions, TimeProvider, Storage.PageStorageRefresh)
MethodGetValueAsync(PagePath, string, CancellationToken)
Inherited from Pages.IPageStateStore.GetValueAsync.
Parameters
path- The page whose state is read.
key- The key to read.
cancellationToken- Cancels the read.
Returns
null when the key is absent.MethodSetValueAsync(PagePath, string, string, CancellationToken)
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)
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
MethodDeleteValueAsync(PagePath, string, CancellationToken)
Inherited from Pages.IPageStateStore.DeleteValueAsync.
Parameters
path- The page whose state is written.
key- The key to remove.
cancellationToken- Cancels the write.
Returns
MethodListKeysAsync(PagePath, CancellationToken)
Inherited from Pages.IPageStateStore.ListKeysAsync.
Parameters
path- The page whose keys are listed.
cancellationToken- Cancels the read.
Returns
MethodGetValuesAsync(PagePath, CancellationToken)
Inherited from Pages.IPageStateStore.GetValuesAsync.
Parameters
path- The page whose state is read.
cancellationToken- Cancels the read.
Returns
Pages.SqlitePageStore
MethodSqlitePageStore(Storage.StorageDbContext, ILogger<Pages.SqlitePageStore>, Storage.PageStorageRefresh, string)
MethodStoreRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, ILogger logger, CancellationToken cancellationToken)
Parameters
database- The context to write through.
template- The revision to store.
logger- Where a retry is recorded.
cancellationToken- Cancels the write.
Returns
MethodWriteRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, CancellationToken cancellationToken)
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)
Parameters
database- The context to write through.
template- The revision the head should point at.
cancellationToken- Cancels the write.
MethodRegenerateRevision(Pages.PageTemplate template)
Parameters
template- The revision that collided.
MethodTryStoreRevisionAsync(Storage.StorageDbContext database, Pages.PageTemplate template, string expectedHash, ILogger logger, CancellationToken cancellationToken)
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
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
PropertySilenceSeconds
PropertyMaxSeconds
PropertySilence
PropertyMax
MethodFromConfiguration(IConfiguration configuration)
Pages:Stream.Parameters
configuration- The application configuration.
Exceptions
MethodFromConfiguration(Configuration.ConfigurationReader reader)
Pages:Stream into the caller's report.Parameters
reader- A reader opened on
Pages:Stream, which the caller completes.
Pages.ViewCredential
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
MethodViewCredential(Uri origin, string token)
Parameters
origin- The site's origin, from SiteOptions.
token- The run's secret, which never leaves this object.
PropertyOrigin
PropertyName
Inherited from Pages.IOutboundCredential.Name.
PropertyHeader
Inherited from Pages.IOutboundCredential.Header.
PropertyHeaderValue
Inherited from Pages.IOutboundCredential.HeaderValue.
MethodAppliesTo(Uri)
MethodToString()
Returns
Shell
Shell.ShellCatalogue
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
PropertyRoutes
PropertyReserved
MethodLinks(string path, string query, string editorPath)
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.
MethodIsFor(ShellLink link, bool authenticated)
Parameters
link- The link to test.
authenticated- Whether the visitor has signed in.
MethodIsCurrent(ShellLink link, string path)
Parameters
link- The link to test.
path- The canonical request path.
MethodText(PagePath path)
Parameters
path- A canonical key.
Shell.ShellEntry
MethodShellEntry(Shell.ShellMenu[] Menus)
Parameters
Menus- The menus it appears in, if any.
PropertyMenus
MethodHref(string editorPath)
Parameters
editorPath- The editor's own key, which is configuration.
Shell.ShellMenu
MethodShellMenu(ShellSection Section, ShellAudience Audience, int Order, string Text, ShellMatch Match)
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
PropertyAudience
PropertyOrder
PropertyText
PropertyMatch
Shell.ShellPage
FieldHome
FieldEditor
Pages:Editor:Key.FieldHelp
Shell.ShellPageLink
MethodShellPageLink(Shell.ShellPage Page, Shell.ShellMenu[] Menus)
Parameters
Page- Which page, as a token, because the editor's key is configuration.
Menus- The menus it appears in.
PropertyPage
MethodHref(string)
Inherited from Shell.ShellEntry.Href.
Parameters
editorPath- The editor's own key, which is configuration.
Shell.ShellRoute
MethodShellRoute(string Key, string Methods, ShellAudience Audience, string Description, Shell.ShellMenu[] Menus)
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
PropertyMethods
PropertyAudience
PropertyDescription
PropertyAccessNote
PropertyAccess
MethodHref(string)
Inherited from Shell.ShellEntry.Href.
Parameters
editorPath- The editor's own key, which is configuration.
Storage
Storage.PageStorageRefresh
Storage.PageStorageSampler
MethodPageStorageSampler(IServiceScopeFactory, Pages.PageMetrics, Storage.PageStorageRefresh, ILogger<Storage.PageStorageSampler>)
Storage.SqliteCommandExtensions
MethodAddParameter(DbCommand command, string name, object value)
Parameters
command- The command to add it to.
name- The parameter's name, sigil included.
value- The value to bind.
Storage.SqliteErrors
FieldRetryCount
MethodIsUniqueViolation(DbUpdateException exception)
Parameters
exception- The failure a save threw.
Storage.StorageDbContext
MethodStorageDbContext(DbContextOptions<Storage.StorageDbContext>)
Storage.Migrations
Storage.Migrations.AddAssistantMemory
integrity-check.
MethodUp(MigrationBuilder)
Inherited from Migration.Up.
MethodDown(MigrationBuilder)
Inherited from Migration.Down.
MethodBuildTargetModel(ModelBuilder)
Inherited from Migration.BuildTargetModel.
Storage.Migrations.AddOwnerInterrupts
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
MethodUp(MigrationBuilder)
Inherited from Migration.Up.
MethodDown(MigrationBuilder)
Inherited from Migration.Down.
MethodBuildTargetModel(ModelBuilder)
Inherited from Migration.BuildTargetModel.
Storage.Migrations.AddPageRevisionTemplateHasCode
MethodUp(MigrationBuilder)
Inherited from Migration.Up.
MethodDown(MigrationBuilder)
Inherited from Migration.Down.
MethodBuildTargetModel(ModelBuilder)
Inherited from Migration.BuildTargetModel.
Storage.Migrations.AddPageRevisionTemplateKind
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
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
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
MethodUp(MigrationBuilder)
Inherited from Migration.Up.
MethodDown(MigrationBuilder)
Inherited from Migration.Down.
MethodBuildTargetModel(ModelBuilder)
Inherited from Migration.BuildTargetModel.
Storage.Migrations.AddRunEstimate
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
MethodHash(Users.LocalUser user, string password)
Parameters
user- The account the hash belongs to.
password- The plaintext password.
MethodVerify(Users.LocalUser user, string password)
Parameters
user- The account to check.
password- The candidate password.
Returns
MethodVerifyDummy(string password)
Parameters
password- The candidate password.
Returns
false; the point is the time spent hashing.Users.IUserConsole
MethodReadPassword(string)
MethodWriteLine(string)
MethodWriteError(string)
Users.IUserStore
MethodFindAsync(string userName, CancellationToken cancellationToken)
Parameters
userName- The normalised name.
cancellationToken- Cancels the read.
MethodTryAddAsync(Users.LocalUser user, CancellationToken cancellationToken)
Parameters
user- The account to add.
cancellationToken- Cancels the write.
Returns
true when the account was added.MethodUpdateHashAsync(string userName, string passwordHash, CancellationToken cancellationToken)
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)
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)
Parameters
cancellationToken- Cancels the read.
MethodRemoveAsync(string userName, CancellationToken cancellationToken)
Parameters
userName- The normalised name.
cancellationToken- Cancels the write.
Returns
true when the account existed.Users.LocalUser
PropertyUserName
PropertyPasswordHash
PropertySecurityStamp
PropertyCreatedAt
Users.PasswordPolicy
FieldMinimumLength
FieldMaximumLength
MethodValidate(string password)
Parameters
password- The password to test.
Exceptions
ArgumentException- The password is outside the accepted length.
Users.PasswordService
MethodHash(Users.LocalUser, string)
Inherited from Users.IPasswordService.Hash.
Parameters
user- The account the hash belongs to.
password- The plaintext password.
MethodVerify(Users.LocalUser, string)
Inherited from Users.IPasswordService.Verify.
Parameters
user- The account to check.
password- The candidate password.
Returns
MethodVerifyDummy(string)
Inherited from Users.IPasswordService.VerifyDummy.
Parameters
password- The candidate password.
Returns
false; the point is the time spent hashing.Users.SecurityStamp
MethodCreate()
Users.SqliteUserStore
MethodSqliteUserStore(Storage.StorageDbContext, ILogger<Users.SqliteUserStore>)
MethodFindAsync(string, CancellationToken)
Inherited from Users.IUserStore.FindAsync.
Parameters
userName- The normalised name.
cancellationToken- Cancels the read.
MethodTryAddAsync(Users.LocalUser, CancellationToken)
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)
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)
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)
Inherited from Users.IUserStore.ListAsync.
Parameters
cancellationToken- Cancels the read.
MethodRemoveAsync(string, CancellationToken)
Inherited from Users.IUserStore.RemoveAsync.
Parameters
userName- The normalised name.
cancellationToken- Cancels the write.
Returns
true when the account existed.Users.SystemUserConsole
MethodReadPassword(string)
Inherited from Users.IUserConsole.ReadPassword.
Users.UserCommands
FieldName
MethodIsCommand(string[] args)
Parameters
args- The process arguments.
MethodRunAsync(string[] args, IServiceProvider services, CancellationToken cancellationToken)
Parameters
args- The arguments after
users. services- The application's service provider.
cancellationToken- Cancels the command.
Returns
Users.UserName
FieldMaximumLength
MethodNormalize(string userName)
Parameters
userName- The text submitted by a login form or the CLI.
Returns
Exceptions
ArgumentException- The text is empty, too long or contains control characters.
Work
Work.BoundedWorkQueue<T>
Type parameters
T- The work item.
MethodBoundedWorkQueue(int)
Type parameters
T- The work item.
MethodTryReserve()
Returns
false when every slot is taken.MethodReleaseReservation()
MethodTryEnqueueReserved(T item)
Parameters
item- The work to queue.
Returns
false when the channel would not accept it.MethodTryEnqueue(T item)
Parameters
item- The work to queue.
Returns
false when the queue is full.MethodReadAllAsync(CancellationToken cancellationToken)
Parameters
cancellationToken- Cancels the read.
Work.IWorkerStore
MethodGetAsync(PagePath worker, CancellationToken cancellationToken)
Parameters
worker- The worker's canonical key.
cancellationToken- Cancels the read.
Returns
null when nothing is stored there.MethodTrySetImageAsync(string revisionId, string template, Pages.PageImage image, CancellationToken cancellationToken)
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
Work.JobEnd
FieldCompleted
FieldCancelled
FieldSilence
Pages:Jobs:SilenceSeconds.FieldCeiling
Pages:Jobs:MaxDurationSeconds.Work.JobLifetime
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)
Parameters
options- The job's bounds.
PropertyEnd
PropertyToken
MethodReArm()
MethodPause()
MaxDurationSeconds.
MethodResume()
MethodCancel()
MethodDispose()
Inherited from IDisposable.Dispose.
Work.PageJob
MethodPageJob(string id, PagePath worker, PagePath page, PageUser owner, string input, Pages.PageJobOptions options, TimeProvider clock)
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
nullwhen there was none. options- The job's bounds.
clock- Where the times come from.
PropertyId
PropertyWorker
PropertyPage
PropertyOwner
PropertyInput
null.PropertyStartedAt
PropertyJournal
PropertyLifetime
MethodSnapshot()
MethodMarkRunning()
MethodTrySend(string message)
Parameters
message- The message.
Returns
MethodReceiveAsync(TimeSpan? wait, CancellationToken aborted)
Parameters
wait- How long to wait, or
nullto wait until the job ends. aborted- Cancels the wait when the job must stop.
Returns
null when the wait elapsed or the job ended.MethodEnd(PageJobState state, string failure)
Parameters
state- How it ended.
failure- Why it failed, or
nullwhen it did not.
MethodDispose()
Inherited from IDisposable.Dispose.
Work.PageJobJournal
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)
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)
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()
MethodWaitAsync(TimeSpan wait, CancellationToken cancellationToken)
Parameters
wait- How long to wait.
cancellationToken- Cancels the wait.
Returns
MethodRead(long after)
Parameters
after- The last sequence the caller has seen;
0reads from the start.
Work.PageJobJournal.Snapshot
MethodSnapshot(IReadOnlyList<PageJobEvent> Events, long Next, bool Reset)
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
PropertyNext
PropertyReset
Work.PageJobQueue
MethodPageJobQueue(Pages.PageJobOptions)
Work.PageJobRequest
MethodPageJobRequest(string Id, PagePath Worker, PagePath Page, PageUser Owner)
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
PropertyWorker
PropertyPage
PropertyOwner
Work.PageJobRunner
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>)
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 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 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
MethodStartAsync(PagePath page, string workerKey, string firstMessage, PageUser owner, CancellationToken cancellationToken)
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
nullwhen 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)
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)
Parameters
jobId- The job's id.
owner- The signed-in visitor.
MethodList(PageUser owner)
Parameters
owner- The signed-in visitor.
MethodReadEventsAsync(string jobId, long after, TimeSpan wait, PageUser owner, CancellationToken cancellationToken)
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)
Parameters
page- The page asking, for the log line.
jobId- The job's id.
owner- The signed-in visitor.
Returns
false.MethodFind(string jobId)
Parameters
jobId- The job's id.
Returns
null when no job has that id.Work.ScopedWorkerStore
MethodScopedWorkerStore(IServiceScopeFactory)
MethodGetAsync(PagePath, CancellationToken)
Inherited from Work.IWorkerStore.GetAsync.
Parameters
worker- The worker's canonical key.
cancellationToken- Cancels the read.
Returns
null when nothing is stored there.MethodTrySetImageAsync(string, string, Pages.PageImage, CancellationToken)
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
Work.WorkerContext
MethodWorkerContext(Work.PageJob, Pages.PageCapabilities, Pages.PageJobOptions, ILogger)
PropertyWorker
Inherited from IWorkerContext.Worker.
PropertyInput
null when it had none.Inherited from IWorkerContext.Input.
PropertyAborted
Inherited from IWorkerContext.Aborted.
PropertyCapabilities
Inherited from IWorkerContext.Capabilities.
MethodLog(string)
Inherited from IWorkerContext.Log.
Parameters
message- The message.
MethodLogWarning(string)
Inherited from IWorkerContext.LogWarning.
Parameters
message- The message.
MethodLogError(string)
Inherited from IWorkerContext.LogError.
Parameters
message- The message.
MethodReceiveAsync(double?)
Inherited from IWorkerContext.ReceiveAsync.
Parameters
waitSeconds-
How long to wait, capped by
Pages:Jobs:MaxWaitSeconds. Omitted ornullwaits until a message arrives or the job ends.
Returns
null when the wait elapsed or the job can no longer receive —
Aborted tells the two apart. A wait is not silence: it pauses the job's silence
clock, so a worker waiting on its owner is bounded by the job's ceiling instead.
MethodPublish(string, string)
Inherited from IWorkerContext.Publish.
Parameters
type- What the event is, such as
deltaordone. dataJson- The event's text or JSON, bounded by
Pages:Jobs:MaxEventBytes.