AppSurface Search
Section API Reference
API Reference Language: C# Component: AppSurfaceDurableWorker Audience: developer

AppSurfaceDurableWorker

Namespaces

Type

WorkerApplication

Source

Builds and starts the passive, application-owned Durable external-activation host.

Remarks

Call CreateBuilder(string[]) , configure a production authentication scheme and the named ActivationAuthorization policy when outside Development, then call BuildAsync(WebApplicationBuilder, CancellationToken) followed by StartAsync(WebApplication, CancellationToken) . Build validates authentication before opening a database connection; startup then performs read-only schema, StoreId, and epoch checks before listening. The returned application owns the restricted data sources and OpenTelemetry provider and must be disposed by its caller. Each built host receives a fresh privacy-safe worker identity so concurrent hosts have independent heartbeat and claim ownership, including when they share one process. No worker service, migration, grant, or epoch mutation is started here.

Method

CreateBuilder

WebApplicationBuilder CreateBuilder(string[] args)
Source

Creates a web builder rooted at the generated settings copy with loopback-only listener defaults and DI validation.

Parameters

  • args
    Command-line arguments consumed by ASP.NET Core configuration.

Returns

A builder that the application may configure before calling BuildAsync(WebApplicationBuilder, CancellationToken) .

Exceptions

  • ArgumentNullException
    args is null.
Method

BuildAsync

Task<WebApplication> BuildAsync(WebApplicationBuilder builder, CancellationToken cancellationToken = default)
Source

Validates composition, performs bounded read-only PostgreSQL startup checks, and returns an unstarted host.

Parameters

  • builder
    Application-owned web builder, including any production authentication registrations.
  • cancellationToken
    Cancels the complete ten-second startup phase.

Returns

A passive application that has not opened its listener.

Exceptions

  • ArgumentNullException
    builder is null.
  • InvalidOperationException
    Settings or authentication composition is invalid, or storage is incompatible.
  • TimeoutException
    The combined build and startup validation phase exceeds ten seconds.
  • OperationCanceledException
    cancellationToken is canceled.

Remarks

In Development this method registers the sample bearer scheme and named policy from the required DevelopmentTokenKey configuration value. In other environments the caller must register a real application-selected scheme and a named policy that requires an authenticated user. Policy and scheme validation runs before any PostgreSQL connection is opened. Store validation is read-only; a missing or incompatible schema, configured StoreId mismatch, or epoch mismatch fails closed.

Method

BuildWithStartupSeamsAsync

Task<WebApplication> BuildWithStartupSeamsAsync(WebApplicationBuilder builder, Func<WorkerHostSettings, WorkerDataSources> dataSourceFactory, Func<WorkerDataSources, CancellationToken, ValueTask<DurableRuntimeSchemaStatus>> schemaStatusReader, TimeSpan startupBudget, CancellationToken cancellationToken = default)
Source

Builds through explicit startup seams for friend-assembly host contract tests.

Parameters

  • builder
    Application-owned builder.
  • dataSourceFactory
    Creates the pair of restricted data sources after authentication validation.
  • schemaStatusReader
    Returns the read-only schema observation for the runtime source.
  • startupBudget
    Positive bounded budget for the test startup lifecycle.
  • cancellationToken
    Cancels the startup lifecycle.

Returns

A built but unstarted application when the configured observation is compatible.

Remarks

This seam is internal so installed application consumers continue to use the production PostgreSQL reader.

Method

StartAsync

Task StartAsync(WebApplication app, CancellationToken cancellationToken = default)
Source

Starts the listener using the remaining portion of the same ten-second startup budget.

Parameters

  • app
    Built host returned by BuildAsync(WebApplicationBuilder, CancellationToken) .
  • cancellationToken
    Cancels listener startup.

Returns

A task that completes when the HTTP listener is active.

Exceptions

  • ArgumentNullException
    app is null.
  • TimeoutException
    The remaining ten-second startup budget expires before the listener opens.
  • OperationCanceledException
    cancellationToken is canceled.
Method

ValidateAuthenticationComposition

void ValidateAuthenticationComposition(IServiceCollection services)
Source

Validates the named authenticated policy and every scheme it can select before database access.

Parameters

  • services
    Builder registrations containing application-selected authentication and authorization.

Remarks

This intentional short-lived provider resolves only framework auth/authorization metadata. The registered application host is built once after validation; no PostgreSQL source is present in this validation provider.

Method

ConfigureAuthentication

void ConfigureAuthentication(WebApplicationBuilder builder, string? developmentToken)
Source

Maps only the supported Development auth defaults and closed authorization policy.

Parameters

  • builder
    Application web builder.
  • developmentToken
    Validated Development token, or null outside Development.
Method

ValidateSchemaIdentity

void ValidateSchemaIdentity(DurableRuntimeSchemaStatus status, WorkerHostSettings settings)
Source

Checks the read-only schema observation against both explicitly configured process identities.

Parameters

  • status
    Published PostgreSQL schema-manager observation.
  • settings
    Validated application settings.
Method

DisposeFailedBuildAsync

ValueTask DisposeFailedBuildAsync(WebApplication? app, WorkerDataSources? dataSources)
Source

Attempts every resource disposal after an unsuccessful build.

Parameters

  • app
    Built application, when ownership has transferred to its service provider.
  • dataSources
    Pre-build data-source owner, when the application did not take ownership.
Type

WorkerHostSettings

Source

Contains validated runtime settings captured before resources or listeners are created.

Parameters

  • DispatcherConnectionString
    Restricted payload-free discovery connection.
  • RuntimeConnectionString
    Distinct restricted mutation and heartbeat connection.
  • StoreId
    Expected provisioned StoreId.
  • RuntimeEpoch
    Expected provisioned active runtime epoch.
  • RuntimeRole
    Exact login role used by the runtime safety options.
  • MaximumPoolSize
    Bounded pool size applied to both sources.
  • ConnectionTimeoutSeconds
    Bounded connection timeout applied to both sources.
  • CommandTimeoutSeconds
    Bounded command timeout applied to both sources.
  • Activation
    Validated Work-only pump, request, and body-read budgets.
  • DevelopmentToken
    Development-only bearer token; null outside Development.
  • OtlpEndpoint
    Validated optional OTLP endpoint.

Remarks

Diagnostic formatting includes only StoreId and runtime epoch. Individual properties still contain credentials or application configuration and must not be logged directly.

Method

PrintMembers

bool PrintMembers(System.Text.StringBuilder builder)
Source

Restricts record diagnostic formatting to the two non-secret provisioned identities.

Parameters

  • builder
    Destination used by the compiler-generated record formatter.

Returns

True because both identity members were appended.

Method

Read

WorkerHostSettings Read(IConfiguration configuration, IWebHostEnvironment environment)
Source

Reads all non-secret settings and rejects malformed or out-of-range values without echoing them.

Parameters

  • configuration
    Application configuration.
  • environment
    Web host environment.

Returns

Immutable settings snapshot.

Exceptions

  • InvalidOperationException
    A required value is missing or a configured value is outside its contract.
Method

ParseRuntimeRole

string ParseRuntimeRole(string connectionString)
Source

Reads a required bounded identity from a connection string without logging the connection text.

Parameters

  • connectionString
    Configured connection string.

Returns

The nonblank login role.

Method

RequireText

string RequireText(IConfiguration configuration, string key)
Source

Reads a nonblank configuration value and reports only its key on failure.

Parameters

  • configuration
    Configuration source.
  • key
    Required setting name.

Returns

The configured value.

Method

RequireGuid

Guid RequireGuid(IConfiguration configuration, string key)
Source

Reads a nonempty Guid setting.

Parameters

  • configuration
    Configuration source.
  • key
    Setting name.

Returns

The parsed identity.

Method

ReadInteger

int ReadInteger(IConfiguration configuration, string key, int defaultValue, int minimum, int maximum)
Source

Reads an invariant integer and enforces its inclusive range.

Parameters

  • configuration
    Configuration source.
  • key
    Setting name.
  • defaultValue
    Value used only when the key is absent.
  • minimum
    Inclusive minimum.
  • maximum
    Inclusive maximum.

Returns

The validated value.

Property

IsDevelopment

bool IsDevelopment { get; init; } Source

Gets whether the settings were read for the Development environment.

Type

ActivationSettings

Source

Captures the host-only numeric contracts for a payload-free activation and its ingress body phase.

Parameters

  • PumpMaximumItems
    Configured maximum claims, 1–10,000.
  • PumpDiscoveryBudget
    Discovery duration, 1–300 seconds.
  • RequestBudget
    Cooperative service duration, 1–4,294,967 seconds.
  • BodyReadBudget
    Independent unknown-length body deadline, 1–300 seconds.
Type

WorkerStartupDeadline

Source

Owns one shared monotonic deadline for configuration, validation, and listener startup.

Parameters

  • StartedAtTimestamp
    Monotonic timestamp captured at build entry.
  • Budget
    The fixed total startup/listener budget.
Method

GetRemaining

TimeSpan GetRemaining()
Source

Gets the remaining startup time without consulting wall-clock time.

Returns

Zero after the fixed budget expires.

Method

ThrowIfExpired

void ThrowIfExpired()
Source

Throws a stable timeout when synchronous composition exhausts the shared budget.

Type

WorkerDataSources

Source

Owns distinct dispatcher and runtime sources and disposes both even if one disposal fails.

Parameters

  • Dispatcher
    Payload-free global discovery source.
  • Runtime
    Restricted mutation and heartbeat source.
  • RuntimeRole
    Exact configured runtime login role.
Method

Create

WorkerDataSources Create(WorkerHostSettings settings)
Source

Creates distinct bounded data sources only after authentication composition is validated.

Parameters

  • settings
    Validated connection and pool settings.

Returns

Owned source pair.

Method

DisposeAsync

ValueTask DisposeAsync()
Source

Disposes both restricted sources and preserves every disposal failure.

Method

CreateDataSource

NpgsqlDataSource CreateDataSource(string connectionString, int maximumPoolSize, int connectionTimeoutSeconds, int commandTimeoutSeconds, string settingName)
Source

Applies the documented bounded pool and timeout defaults without changing credentials or role identity.

Parameters

  • connectionString
    Restricted application-owned connection string.
  • maximumPoolSize
    Validated pool size.
  • connectionTimeoutSeconds
    Validated connection timeout.
  • commandTimeoutSeconds
    Validated command timeout.
  • settingName
    Configuration key used for safe failure reporting.

Returns

A newly constructed, unopened data source.