Services

Remarks

Options validation catches missing or blank names. This startup check catches a misspelled name before AppSurface Docs maps an authorization-protected raw-source endpoint. The package deliberately resolves the host policy but never registers authentication schemes, identities, or a policy of its own.

Remarks

The service performs best-effort validation so a broken stored release tree becomes unavailable without preventing healthy versions or the live preview surface from loading. Validation is intentionally release-local: every version is checked independently for a readable tree root, the required landing and search pages, the search index, and the shared search runtime assets that exact-version pages depend on. Exact trees are otherwise treated as immutable, self-contained artifacts: outline-aware and rich-authoring exports should include the page-local runtimes they reference, while historical trees are not crawled or upgraded at host startup. Public AppSurfaceDocsResolvedVersion.AvailabilityIssue values are sanitized for archive UI consumption, while filesystem paths and exception details stay in structured logs only.

Remarks

Disabled means the host is running with versioning off, so callers should treat the live docs surface as the only public experience and skip published-release archive UI entirely.

EnabledWithoutCatalog means versioning was turned on but no catalog path was configured, so callers can still expose the live preview surface but should not expect any published releases to resolve.

PublicVersions preserves the ordering from Versions after filtering by AppSurfaceDocsVersionVisibility.Public only. Public-but-unavailable releases remain in that list so the archive can surface their degraded status instead of pretending they do not exist.

Aliases contains operator-facing alias resolution state in authored order. Consumers that render the public archive must first create a safe projection; AppSurfaceDocsResolvedVersionAlias.ConfiguredVersion may identify hidden configuration and must not be serialized into reader-facing markup.

Remarks

The helper reads at most maxFileSizeBytes + 1 bytes so oversized files can be rejected without loading the whole source into memory. Seekable streams still report their full file length in diagnostics when available.

Remarks

Callers should branch on Included before using Source . Skipped results are intended to let harvesters continue processing sibling files while surfacing a visible diagnostic.

Remarks

The warning is advisory and does not fail startup. This preserves compatibility for hosts that intentionally enforce diagnostics access through their application pipeline, reverse proxy, or network boundary, while making risky package exposure visible during deployment.

Remarks

This builder only uses DocsUrlBuilder and built-in public-section route contracts. It must not inspect harvested docs, search snapshots, or the missing request path. That constraint keeps standalone 404 pages deterministic during cold starts and prevents stale or hostile request paths from shaping recovery navigation. Callers that need search-result or representative-document fallback behavior should keep that logic in the search surface and adapt these links only as static route-safe entries.

Remarks

The verifier treats the version catalog as trusted host configuration. It proves that the local exact-version tree matches the digest pinned by that catalog; it does not prove who built the archive or replace future signed attestation support.

Remarks

The production adapter reads the physical release tree. Tests use custom adapters to exercise portable failure branches such as unreadable files without depending on platform-specific chmod behavior.

Remarks

Candidates are produced only for variants that have a public route and a configured locale route prefix. Source paths and public route paths are normalized relative docs paths, not absolute URLs.

Remarks

The catalog deliberately separates source identity from public route identity: source path -> internal lookup and authoring provenance public route path -> browser-facing canonical URL redirect alias -> declared or Markdown source-shaped URL that redirects to public route Controllers render only public canonical winners. Declared aliases and Markdown source-shaped paths for public winners redirect to the canonical route, while non-Markdown source paths, collision losers, and reserved routes stay non-public. Link builders can still resolve source paths so authored Markdown stays source-friendly without rendering source-shaped URLs into the reader-facing surface.

Remarks

The resolved theme is safe to cache as a singleton because it contains only preset names, density/chrome flags, and sanitized CSS custom property declarations. Razor views emit these values into the exported HTML so live docs, static export, and published archives share the same frozen visual contract.

Remarks

Hosts configure AppSurfaceDocsThemeOptions , while this policy keeps every consumer on one resolved theme boundary. Run Normalize during post-configuration before calling Validate or Resolve .

Remarks

Implement this for best-effort harvesters whose diagnostics should be visible to operators but whose empty, failed, timed-out, or canceled state must not decide whether DocHarvestHealthStatus.Failed is returned.

Remarks

ConfiguredVersion is operator-side configuration and may identify a hidden release. Public archive consumers must use a deliberate safe projection instead of serializing this record. TargetVersion is populated only for a known public target; it is the same resolved-version object used by exact-version mounts.

Remarks

The validator is stateless and thread-safe. Callers should normalize or validate before matching: backslashes are converted to / , configured patterns are trimmed, and rooted, URI-like, drive-rooted, control-character, query, fragment, and parent-directory paths are rejected. NormalizeSlashes only changes separators; it does not perform validation by itself.

Remarks

Named Docs products own isolated options and aggregators, so the legacy singleton preflight services cannot validate or warm them. This service runs after endpoint mapping, when the registry has constructed the immutable runtime snapshots, and preserves the same Markdown-policy validation, diagnostics warning, and harvest startup semantics that AddAppSurfaceDocs() provides for a legacy single-instance host.

Remarks

IAppSurfaceDocsHtmlSanitizer exists to normalize rendered package documentation fragments before AppSurface Docs displays them. It is not a general-purpose user-generated-content sanitizer, JavaScript policy, or replacement for a host-owned Content Security Policy. Unsupported elements or attributes may be removed.

Remarks

The harvester is enabled by default through AppSurfaceDocsJavaScriptHarvestOptions.Enabled and scans repository-relative JavaScript candidates that pass the shared harvest path policy. V1 is deliberately strict: broad discovery requires @public , treats @internal , @private , and @ignore as hard exclusions, skips file and directory reparse points before reads or descent, and turns unsupported public shapes into harvest diagnostics instead of partial docs.

Remarks

Host applications that implement IRazorWireStreamAuthorizer , or legacy IRazorWireChannelAuthorizer compatibility policies, should use IsHarvestProgressChannel(string?) when applying production authorization rules to the AppSurface Docs live harvest progress stream. Prefer the predicate over raw string comparison so future docs-owned stream naming remains centralized.

Remarks

This type intentionally stays internal. Raw Markdown must not become part of DocNode , the search index, or the public custom-harvester contract.

Remarks

The extension deliberately builds on Markdig's fenced custom-container parser. The harvester first recognizes valid tabs and emits their complete server-rendered baseline; this extension then renders callouts, preserves generic custom containers, and leaves invalid rich directives visible as source markers with their body intact instead of guessing them into an interactive component.

Remarks

The aggregate health snapshot reads these diagnostics only after the harvester participates in the current snapshot. Failed, timed-out, canceled, or disabled harvesters surface through the primary harvester-health diagnostic instead.

Remarks

Published search indexes are archive metadata, not a general URL surface. Archive payloads must store canonical /docs -rooted document paths so the published-tree rewriter can safely rebase them for aliases, exact versions, custom route roots, and request path bases at serve time. The served-path entry point is a defense-in-depth check for already-rebased browser links; it must not be used to validate immutable archive contents.

Remarks

Use this abstraction when Markdown rendering needs package-owned code HTML without coupling callers to a specific highlighter implementation. Implementations must return HTML-safe output for direct insertion into docs rendering templates, including escaped plaintext fallback for unsupported languages or failed highlighting.

Remarks

This service accepts only validated, sanitized product-intelligence events. It stores no raw event payloads, raw search text, URLs, identity, cookies, request bodies, or free-form comments. The rolling window exists only to bound process memory while preserving enough recent aggregate signal for maintainer diagnostics.

Remarks

The manifest stores both source paths, such as guides/start.md , and canonical browser paths, such as guides/start.md.html . Query strings and fragments are intentionally ignored because anchors and query parameters decorate a page target rather than defining a separate harvested document.

Remarks

AppSurface Docs starts from the HtmlSanitizer defaults, adds the package-owned content tags section , article , header , details , summary , pre , code , and span , and allows the class , id , open , role , aria-label , and package-owned rich-authoring and code data-* attributes. The sanitizer explicitly removes style from the default attribute set so harvested Markdown, generated API HTML, and server-side highlighted code can keep structural hooks while inline presentation and unsafe markup are stripped. Callers should pass already-rendered AppSurface Docs HTML through this sanitizer before display or export; supported semantic wrappers and token spans are preserved, while scripts, event handlers, inline styles, and unsupported attributes are discarded.

Remarks

This internal session accepts only a closed phase enum and numeric document deltas. It deliberately cannot carry a file name, path, source text, exception, percentage, or arbitrary activity string. Custom IDocHarvester implementations never receive this type and retain the established status-only progress contract.

Remarks

The service is always registered by AddAppSurfaceDocs() . By default it starts the same memoized harvest used by docs requests through their shared AppSurfaceDocsHarvestCoordinator . Blocking and strict startup await that same task, so completed warmup is immediately visible to requests even with a zero request-wait budget. Strict mode fails startup only when the aggregate snapshot is failed.

Remarks

The graph is the Phase 1 localization handoff between harvesters, route identity, navigation, fallback, and search projection code. Consumers should use this graph instead of re-inferring locale state from source paths.

Remarks

Locale and translation key may be authored in metadata, inferred from a configured filename suffix, inferred from a locale folder when a translation key is authored, or defaulted to the configured default locale. Public route paths are null when route identity rejected the source path.

Remarks

This Phase 1 builder is intentionally internal. It records document identity and locale facts without changing the existing visible route or search behavior. Later slices should consume this graph instead of re-inferring locale state in controllers, views, or JavaScript.

Remarks

The resolved identity intentionally stores only app-relative or app-root paths. Razor views apply the current request path base at render time with Url.PathBaseAware(...) , so singleton identity resolution stays safe for virtual-directory deployments and tests that render the same service provider under multiple path bases.

Remarks

This filter protects the docs-owned harvest progress channel even when a host registers an IRazorWireStreamAuthorizer after AddAppSurfaceDocs() and thereby replaces the normal Docs wrapper in Microsoft DI. The filter only gates the reserved AppSurface Docs channel; non-docs channels continue to the host authorizer unchanged.

Remarks

Policy order is intentionally fixed: built-in source candidates are checked first, then global includes, source-specific includes, default exclusion groups and their allows, repository VCS ignore rules when a snapshot supplies them, global excludes, and source-specific excludes. Default groups protect build output, hidden directories, test projects, and C# source under examples . Directory pruning uses the same defaults and clear /** subtree excludes, but keeps a default-excluded subtree only when a configured group allow can match that directory or one of its descendants.

Remarks

Matching is case-insensitive. MatchFirst is order-dependent and returns the first configured pattern that matches the candidate. Directory helpers are conservative because pruning must never skip a file that a later allow pattern could include; callers should validate and normalize paths before invoking the matcher.

Remarks

This builder centralizes the route contract so controllers, view components, views, and client scripts do not each guess how the docs surface is rooted. RouteRootPath is the stable route-family root used for archive and exact-version routes. CurrentDocsRootPath is the live source-backed docs root used for current docs, search, and current search-index routes. Most consumers should copy Routes rather than assembling route strings or calling lower-level builder methods directly.

Remarks

Consumers should prefer this record when they need well-known AppSurface Docs destinations in host code, operator guidance, generated configuration, or documentation. The values are app-relative. Views and other presentation boundaries apply request PathBase separately before sending browser-facing URLs.

Remarks

The manifest is an internal read model, not a second router. It contains only public canonical winners plus redirect aliases that should recover to those winners. Collision losers, reserved routes, and invalid routes stay represented by diagnostics so export and future consumers do not guess a destination for ambiguous paths.