StellaOps.Workflow.Publisher

Publishes the workflow definitions an application bundles to a workflow engine over HTTP.

PackageStellaOps.Workflow.Publisher
ComponentWorkflow
LicenceBUSL-1.1 (Workflow licence)
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Workflow.Publisher13

StellaOps.Workflow.Publisher namespace

TypeKindDescription
BundledWorkflowrecordA single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler.
HttpWorkflowDefinitionImportTransportclassDefault transport — sends the import request as an HTTP POST to {Endpoint}{CommandPath}.
IBundledWorkflowProviderinterfaceFinds the canonical workflows bundled in plugin assemblies.
IWorkflowDefinitionImportTransportinterfaceTransport used by WorkflowPublisherto deliver a single WorkflowDefinitionImportRequestto the workflow engine’s definition-import endpoint.
PublishSummaryrecordThe outcome of one publish run.
PublisherServiceCollectionExtensionsclassRegisters the workflow publisher.
ReflectionBundledWorkflowProviderclassDefault IBundledWorkflowProvider: scans a provided list of assemblies for the generator-emitted _BundledCanonicalWorkflowRegistry type (in the StellaOps.Workflow.Generated namespace) and reads its Entries field via reflection.
WorkflowDefinitionRemoteDeployRequestrecordWhat WorkflowDefinitionRemoteDeployServicedeploys, and where.
WorkflowDefinitionRemoteDeployResultrecordThe outcome of one remote deployment.
WorkflowDefinitionRemoteDeployServiceclassPushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport.
WorkflowPublisherclassPublishes the canonical workflows bundled in plugin assemblies to a workflow server.
WorkflowPublisherHostedServiceclassRuns WorkflowPublisher.PublishAllAsync(CancellationToken)once on IHostedService.StartAsync(CancellationToken).
WorkflowPublisherOptionsclassConfiguration for the workflow publisher.

BundledWorkflow record

public sealed record BundledWorkflow

A single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler. A runtime-compiled definition has no CanonicalContentHash (the workflow service computes its own). CompilationError is set, and the definition empty, when that runtime compilation failed: the workflow has no canonical definition and cannot be published.

Parameters

BundledWorkflow(string, string, string, string, string, string, string) constructor

public BundledWorkflow(string WorkflowName, string WorkflowVersion, string DisplayName, string CanonicalDefinitionJson, string CanonicalContentHash, string SourceAssemblyName, string? CompilationError = null)

A single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler. A runtime-compiled definition has no CanonicalContentHash (the workflow service computes its own). CompilationError is set, and the definition empty, when that runtime compilation failed: the workflow has no canonical definition and cannot be published.

Parameters

CanonicalContentHash property

public string CanonicalContentHash { get; init; }

The content hash of the canonical definition; empty for a runtime-compiled definition.

CanonicalDefinitionJson property

public string CanonicalDefinitionJson { get; init; }

The canonical definition, as JSON; empty when the compilation failed.

CompilationError property

public string? CompilationError { get; init; }

Why the runtime compilation failed; not set when it succeeded.

DisplayName property

public string DisplayName { get; init; }

The display name.

SourceAssemblyName property

public string SourceAssemblyName { get; init; }

The assembly the workflow comes from.

WorkflowName property

public string WorkflowName { get; init; }

The workflow name.

WorkflowVersion property

public string WorkflowVersion { get; init; }

The workflow version.

HttpWorkflowDefinitionImportTransport class

public sealed class HttpWorkflowDefinitionImportTransport : IWorkflowDefinitionImportTransport

Default transport — sends the import request as an HTTP POST to {Endpoint}{CommandPath}. Hosts that use a different delivery channel (RabbitMQ RPC, gRPC, etc.) should register their own IWorkflowDefinitionImportTransportimplementation before calling AddWorkflowPublisher.

HttpWorkflowDefinitionImportTransport(HttpClient) constructor

public HttpWorkflowDefinitionImportTransport(HttpClient httpClient)

No description.

ImportAsync(WorkflowDefinitionImportRequest, WorkflowPublisherOptions, CancellationToken) method

public Task<WorkflowDefinitionImportResponse> ImportAsync(WorkflowDefinitionImportRequest request, WorkflowPublisherOptions options, CancellationToken cancellationToken)

No description.

IBundledWorkflowProvider interface

public interface IBundledWorkflowProvider

Finds the canonical workflows bundled in plugin assemblies.

Enumerate() method

IReadOnlyList<BundledWorkflow> Enumerate()

Returns the bundled workflows.

Returns

The workflows.

IWorkflowDefinitionImportTransport interface

public interface IWorkflowDefinitionImportTransport

Transport used by WorkflowPublisherto deliver a single WorkflowDefinitionImportRequestto the workflow engine’s definition-import endpoint. Hosts that speak another protocol (RabbitMQ RPC, for example) plug their own implementation here; the default HTTP implementation keeps the publisher runnable out of the box.

ImportAsync(WorkflowDefinitionImportRequest, WorkflowPublisherOptions, CancellationToken) method

Task<WorkflowDefinitionImportResponse> ImportAsync(WorkflowDefinitionImportRequest request, WorkflowPublisherOptions options, CancellationToken cancellationToken)

Sends an import request to the server the options name.

Parameters

Returns

The server’s answer: whether it imported the definition, and the version.

PublishSummary record

public sealed record PublishSummary

The outcome of one publish run.

Parameters

PublishSummary(int, int, int, int, string) constructor

public PublishSummary(int Total, int Imported, int HashSkipped, int Failed, string? DisabledReason)

The outcome of one publish run.

Parameters

DisabledReason property

public string? DisabledReason { get; init; }

Why nothing was published, such as Enabled=false; not set otherwise.

Failed property

public int Failed { get; init; }

The workflows that failed after their retries.

HashSkipped property

public int HashSkipped { get; init; }

The workflows not imported: the server already had the same definition, or the run was dry.

Imported property

public int Imported { get; init; }

The workflows the server imported.

Total property

public int Total { get; init; }

The bundled workflows found.

PublisherServiceCollectionExtensions class

public static class PublisherServiceCollectionExtensions

Registers the workflow publisher.

AddWorkflowPublisher(IServiceCollection, IConfiguration, params Assembly[]) extension method

public static IServiceCollection AddWorkflowPublisher(this IServiceCollection services, IConfiguration configuration, params Assembly[] pluginAssemblies)

PublisherServiceCollectionExtensions.AddWorkflowPublisher(IServiceCollection, params Assembly[]), with WorkflowPublisherOptionsbound from configuration (the section holding the options) instead of the host’s WorkflowPublisherOptions.SectionNamesection.

AddWorkflowPublisher(IServiceCollection, params Assembly[]) extension method

public static IServiceCollection AddWorkflowPublisher(this IServiceCollection services, params Assembly[] pluginAssemblies)

Registers the workflow publisher plus a WorkflowPublisherHostedServicethat runs the publish-all cycle on startup. WorkflowPublisherOptionsare bound from the WorkflowPublisherOptions.SectionNamesection of the host configuration and validated when the host starts: an enabled publisher needs an absolute http or https WorkflowPublisherOptions.Endpoint(unless it runs dry), a command path starting with ‘/’, a positive timeout and non-negative retries.

The default transport is HttpWorkflowDefinitionImportTransport. Hosts that speak another protocol (RabbitMQ RPC, for example) should register their own IWorkflowDefinitionImportTransportBEFORE calling this method; the publisher registers its transport with TryAddSingleton, which keeps the override in place.

Parameters

Returns

The same service collection, for chaining.

ReflectionBundledWorkflowProvider class

public sealed class ReflectionBundledWorkflowProvider : IBundledWorkflowProvider

Default IBundledWorkflowProvider: scans a provided list of assemblies for the generator-emitted _BundledCanonicalWorkflowRegistry type (in the StellaOps.Workflow.Generated namespace) and reads its Entries field via reflection. The workflows the generator could not evaluate at compile time (WF021) are listed in the registry’s RuntimeCompiledWorkflowTypes; the provider creates each and compiles it with WorkflowCanonicalDefinitionCompiler. A workflow the runtime compiler rejects is returned with BundledWorkflow.CompilationErrorset.

ReflectionBundledWorkflowProvider(IEnumerable<Assembly>) constructor

public ReflectionBundledWorkflowProvider(IEnumerable<Assembly> assemblies)

Creates a provider over assemblies.

Parameters

Enumerate() method

public IReadOnlyList<BundledWorkflow> Enumerate()

Returns the bundled workflows.

Returns

The workflows.

WorkflowDefinitionRemoteDeployRequest record

public sealed record WorkflowDefinitionRemoteDeployRequest

What WorkflowDefinitionRemoteDeployServicedeploys, and where.

WorkflowDefinitionRemoteDeployRequest() constructor

public WorkflowDefinitionRemoteDeployRequest()

Creates an instance of WorkflowDefinitionRemoteDeployRequest.

TargetAuthToken property

public string? TargetAuthToken { get; init; }

Optional bearer token the target’s import endpoint requires.

TargetCommandPath property

public string? TargetCommandPath { get; init; }

Path of the target’s import route, appended to WorkflowDefinitionRemoteDeployRequest.TargetServerUrl. Null or blank means WorkflowPublisherOptions.DefaultCommandPath, the route MapWorkflowEndpoints serves.

TargetServerUrl property

public required string TargetServerUrl { get; init; }

The base address of the target workflow server.

WorkflowName property

public required string WorkflowName { get; init; }

The workflow to deploy.

WorkflowVersion property

public string? WorkflowVersion { get; init; }

The version to deploy; the latest when not set.

WorkflowDefinitionRemoteDeployResult record

public sealed record WorkflowDefinitionRemoteDeployResult

The outcome of one remote deployment.

WorkflowDefinitionRemoteDeployResult() constructor

public WorkflowDefinitionRemoteDeployResult()

Creates an instance of WorkflowDefinitionRemoteDeployResult.

Error property

public string? Error { get; init; }

Why the deployment failed, when the export or the push failed.

Succeeded property

public bool Succeeded { get; init; }

Whether the target imported the definition; false also when the target already had the same definition.

TargetServerUrl property

public string? TargetServerUrl { get; init; }

The target workflow server.

ValidationIssues property

public string[]? ValidationIssues { get; init; }

The validation issues the target reported.

WorkflowName property

public string? WorkflowName { get; init; }

The workflow name.

WorkflowVersion property

public string? WorkflowVersion { get; init; }

The version the target reports.

WorkflowDefinitionRemoteDeployService class

public sealed class WorkflowDefinitionRemoteDeployService

Pushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport. The caller supplies the export (usually WorkflowDefinitionDeploymentService.CreateImportRequestAsync), so the service does not depend on the engine. Every failure, of the export or of the push, comes back as an unsuccessful result.

WorkflowDefinitionRemoteDeployService(IWorkflowDefinitionImportTransport, ILogger) constructor

public WorkflowDefinitionRemoteDeployService(IWorkflowDefinitionImportTransport transport, ILogger? logger = null)

Pushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport. The caller supplies the export (usually WorkflowDefinitionDeploymentService.CreateImportRequestAsync), so the service does not depend on the engine. Every failure, of the export or of the push, comes back as an unsuccessful result.

DeployAsync(WorkflowDefinitionRemoteDeployRequest, Func<CancellationToken, Task<WorkflowDefinitionImportRequest>>, CancellationToken) method

public Task<WorkflowDefinitionRemoteDeployResult> DeployAsync(WorkflowDefinitionRemoteDeployRequest request, Func<CancellationToken, Task<WorkflowDefinitionImportRequest?>> exportDefinition, CancellationToken cancellationToken = default)

Exports the definition and pushes it to the target.

Parameters

Returns

The outcome; a failure is a result that did not succeed, never an exception.

WorkflowPublisher class

public sealed class WorkflowPublisher

Publishes the canonical workflows bundled in plugin assemblies to a workflow server.

WorkflowPublisher(IWorkflowDefinitionImportTransport, IBundledWorkflowProvider, IOptions<WorkflowPublisherOptions>, ILogger<WorkflowPublisher>) constructor

public WorkflowPublisher(IWorkflowDefinitionImportTransport transport, IBundledWorkflowProvider provider, IOptions<WorkflowPublisherOptions> options, ILogger<WorkflowPublisher> logger)

Creates the publisher.

Parameters

PublishAllAsync(CancellationToken) method

public Task<PublishSummary> PublishAllAsync(CancellationToken cancellationToken)

Publishes every bundled workflow, retrying each up to WorkflowPublisherOptions.MaxRetriesPerWorkflowtimes with a doubling delay. A workflow without a canonical definition fails. A failure is counted and the run goes on, unless WorkflowPublisherOptions.FailOnErroris set.

Parameters

Returns

The counts of the run.

WorkflowPublisherHostedService class

public sealed class WorkflowPublisherHostedService : IHostedService

Runs WorkflowPublisher.PublishAllAsync(CancellationToken)once on IHostedService.StartAsync(CancellationToken). Wired by AddWorkflowPublisher(). Consumers using a non-.NET-Hosting bootstrap (e.g., a service initializer) can wire WorkflowPublisherinto their own startup mechanism directly without using this service.

WorkflowPublisherHostedService(WorkflowPublisher, ILogger<WorkflowPublisherHostedService>) constructor

public WorkflowPublisherHostedService(WorkflowPublisher publisher, ILogger<WorkflowPublisherHostedService> logger)

Creates the service.

Parameters

StartAsync(CancellationToken) method

public Task StartAsync(CancellationToken cancellationToken)

Runs one publish run; an error stops the host start.

Parameters

Returns

A task that completes when the run ends.

StopAsync(CancellationToken) method

public Task StopAsync(CancellationToken cancellationToken)

Does nothing.

Parameters

Returns

A completed task.

WorkflowPublisherOptions class

public sealed class WorkflowPublisherOptions

Configuration for the workflow publisher. AddWorkflowPublisher binds it from the WorkflowPublisherOptions.SectionNamesection of the host configuration (or from the section a caller passes) and validates it when the host starts.

WorkflowPublisherOptions() constructor

public WorkflowPublisherOptions()

Creates an instance of WorkflowPublisherOptions.

DefaultCommandPath constant

public const string DefaultCommandPath = "/api/workflow/definitions/import"

The import route of the Workflow endpoints (MapWorkflowEndpoints in StellaOps.Workflow.AspNetCore), the default WorkflowPublisherOptions.CommandPath.

SectionName constant

public const string SectionName = "WorkflowPublisher"

The configuration section AddWorkflowPublisher binds.

AuthToken property

public string? AuthToken { get; init; }

Optional bearer token for the outbound request. Typically resolved from an external secret store before binding — the publisher treats this as an opaque bearer value.

CommandPath property

public string CommandPath { get; init; }

Path of the import route, appended to WorkflowPublisherOptions.Endpoint. Defaults to WorkflowPublisherOptions.DefaultCommandPath, the route a host built from MapWorkflowEndpoints serves; set it when the target maps the import elsewhere (for example behind a gateway prefix).

DryRun property

public bool DryRun { get; init; }

When true the publisher logs what it would POST but does not actually POST.

Enabled property

public bool Enabled { get; init; }

When false the publisher does nothing on startup. Handy for per-environment overrides.

Endpoint property

public string Endpoint { get; init; }

Base URL of the workflow service’s REST gateway (no trailing slash).

FailOnError property

public bool FailOnError { get; init; }

If false, publish failures are logged as warnings and the service continues to start up. If true, publish failures throw and take the startup down. Default false so a workflow-service outage does not cascade.

MaxRetriesPerWorkflow property

public int MaxRetriesPerWorkflow { get; init; }

Retries of a failed import, per workflow; not negative. The default is 3.

RetryBaseDelay property

public TimeSpan RetryBaseDelay { get; init; }

The delay before the first retry, doubled for each further retry; not negative. The default is 2 seconds.

ServiceName property

public string? ServiceName { get; init; }

Logical name of the publishing service, sent as the import request’s ImportedBy. A host built from MapWorkflowEndpoints records the authenticated principal as the importer instead.

Timeout property

public TimeSpan Timeout { get; init; }

The timeout of one import request; positive. The default is 30 seconds.