Routers

Routers are a critical component of the Blueprint Runner architecture. They are responsible for directing job calls to the appropriate job handlers based on job IDs. This document explains how routers work, how to configure them, and best practices for implementation.

What are Routers?

In a Blueprint Runner, a router acts as a traffic director for job execution. When a job is called, the router:

Identifies the correct handler for the job based on the job ID
Validates the job parameters
Passes the parameters to the job handler
Returns the result to the consumer

Routers ensure that jobs are executed by the appropriate handlers, making them essential for the proper functioning of your Blueprint Runner.

Router Configuration

Routers are configured when building the Blueprint Runner in the main.rs file of your Blueprint’s binary. The configuration involves:

Creating a new router
Defining routes for each job you have, mapping a job ID to each job in it’s route
Setting a context for the router, which will contain any resources needed by the jobs

Basic Router Setup

A simple router setup might look like this, assuming you have already created a job and context:

use blueprint_sdk::runner::BlueprintRunner;
use blueprint_sdk::Router;
 
let router = Router::builder()
    .route(MY_JOB_ID, my_job)
    .with_context(my_context);

Below is a real example from our Incredible Squaring Blueprint Example:

Layers

Layers are used to filter job calls based on certain criteria. There are two places layers can be used:

A specific Route:
- A job can be given a layer. This can be seen in the above code example, where the job is in the TangleLayer. This allows the consumer, which operates in that layer, to see the results from that job. This simplifies your Blueprint when you have many jobs, routes, and consumers.
A whole Router:
- A layer can be used to filter job calls based on some criteria. This can also be seen in the above code example, where the router is given a filter for the service ID. This allows the router to only process jobs with a matching service ID.

Integration with Other Components

Routers work closely with other Blueprint Runner components:

Producers: Producers pass job calls to the router for processing
Consumers: The router passes job results to Consumers for handling

Next Steps

Now that you understand routers, check out:

Producers - How to capture and process events
Consumers - How to handle job results
Building a Blueprint Runner - Step-by-step guide to building your own Blueprint Runner

Conclusion

Routers are a fundamental component of Blueprint Runners, enabling efficient job execution and management. By properly configuring and utilizing routers, you can build robust and performant Blueprints and AVSs.

Jobs Producers