Struct TopologyBlueprint 

pub struct TopologyBlueprint { /* private fields */ }

A topology blueprint represents a directed graph of components.

A blueprint is assembled by adding components and connecting them together, and then run by adding it to a Supervisor: TopologyBlueprint implements Supervisable, so there is no standalone spawn/run method. A blueprint can only be initialized (and thus run) once.

Implementations

impl TopologyBlueprint

pub fn new(name: &str, component_registry: &ComponentRegistry) -> Self

Creates an empty TopologyBlueprint with the given name.

pub fn with_interconnect_capacity( &mut self, capacity: NonZeroUsize, ) -> &mut Self

Sets the capacity of interconnects in the topology.

Interconnects are used to connect components to one another. Once their capacity is reached, no more items can be sent through until in-flight items are processed. This will apply backpressure to the upstream components. Raising or lowering the capacity allows trading off throughput at the expense of memory usage.

Defaults to 128.

pub fn with_shutdown_timeout(&mut self, timeout: Duration) -> &mut Self

Sets how long the topology waits for components to stop during graceful shutdown.

Defaults to 30 seconds.

pub fn with_health_registry( &mut self, health_registry: HealthRegistry, ) -> &mut Self

Sets the health registry used when the topology is spawned.

This must be set before the blueprint is added to a supervisor; initialization fails otherwise.

pub fn with_memory_limiter( &mut self, memory_limiter: MemoryLimiter, ) -> &mut Self

Sets the memory limiter used when the topology is spawned.

This must be set before the blueprint is added to a supervisor; initialization fails otherwise.

pub fn with_environment_readiness<F>(&mut self, ready: F) -> &mut Self

where F: Future<Output = ()> + Send + 'static,

Sets a readiness signal that must resolve before the topology starts its components.

When set, the topology is still built up front during initialization, but its components are not spawned until the given future resolves (or the topology is asked to shut down first). This is used to defer the topology from processing data until its dependencies – such as the environment provider’s metadata collectors – are ready.

pub fn topology_ready(&mut self) -> TopologyReady

Returns a handle for awaiting the readiness of the topology once it’s running.

This handle depends on observing the readiness of the individual topology components, and so must be called after with_health_registry.

Panics

Panics if the health registry has not been set, or if the blueprint has already been initialized.

pub fn with_ambient_worker_pool(&mut self) -> &mut Self

Configures the topology to use the ambient Tokio runtime for component subtasks.

Component subtasks will be spawned on whatever runtime is currently active when the topology is initialized. This avoids creating a dedicated thread pool, which is useful for resource-constrained environments.

pub fn with_explicit_worker_pool(&mut self, handle: Handle) -> &mut Self

Configures the topology to use an externally provided Tokio runtime for component subtasks.

Component subtasks will be spawned on the runtime associated with the given handle.

pub fn add_source<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: SourceBuilder + Send + 'static,

Adds a source component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_relay<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: RelayBuilder + Send + 'static,

Adds a relay component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_decoder<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: DecoderBuilder + Send + 'static,

Adds a decoder component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_transform<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: TransformBuilder + Send + 'static,

Adds a transform component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_destination<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: DestinationBuilder + Send + 'static,

Adds a destination component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_encoder<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: EncoderBuilder + Send + 'static,

Adds an encoder component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn add_forwarder<I, B>( &mut self, component_id: I, builder: B, ) -> Result<&mut Self, GenericError>

where I: AsRef<str>, B: ForwarderBuilder + Send + 'static,

Adds a forwarder component to the blueprint.

Errors

If the component ID is invalid or the component can’t be added to the graph, an error is returned.

pub fn connect_components<MS, SI, MD, DI>( &mut self, upstream_output_component_ids: SI, downstream_component_ids: DI, ) -> Result<&mut Self, GenericError>

where SI: AsComponentIds<MS>, DI: AsComponentIds<MD>,

Connects one or more upstream component outputs to one or more downstream components.

This method allows for ergonomically defining many-to-one, one-to-many, and many-to-many connections to facilitate common patterns like fanning in many upstream components to a single downstream component, or fanning out a single upstream component to many downstream components.

When both there are both multiple upstream and downstream component IDs, connections resemble a mesh: every upstream component will be connected to every downstream component. This should be rare, but is technically supported.

Errors

If any of the upstream or downstream component IDs are invalid or don’t exist, or if the data types between one of the upstream/downstream component pairs is incompatible, an error is returned.

pub fn connect_components_in_order<IT, I>( &mut self, ordered_component_ids: IT, ) -> Result<&mut Self, GenericError>

where IT: IntoIterator<Item = I>, I: AsRef<str>,

Connects a set of component IDs to one another in a pairwise fashion.

This can be used to connect multiple components – each sharing only a single edge between one another – in a single call instead of multiple calls.

For example, passing ["first", "second", "third"] would connect first’s output to second’s input, and second’s output to third’s input.

One caveat is that only the default output of a component can be used for connections past the first pair, as the identifier given must be able to describe both the component ID to send to as well as the component output ID to connect to the subsequent component. This limitation does not exist on the first component ID, since it is only used in the context of being a component output ID.

Errors

If any of the component IDs are invalid or don’t exist, or if the data types between one of the upstream/downstream component pairs is incompatible, or if less than two component IDs are provided, an error is returned.

Care should be taken on failure as this method will not rollback any previously successful connections, which could leave the blueprint in an indeterminate state if some connections are made prior to hitting an error.

Trait Implementations

impl Supervisable for TopologyBlueprint

fn name(&self) -> &str

Returns the name of the process.

fn shutdown_strategy(&self) -> ShutdownStrategy

Returns the shutdown strategy for the process.

fn initialize<'life0, 'async_trait>( &'life0 self, shutdown: ShutdownHandle, ) -> Pin<Box<dyn Future<Output = Result<SupervisorFuture, InitializationError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Initializes the process asynchronously.