cargo-prosa

ProSA is a framework that handles processors organized around a service bus. As such, ProSA needs to be built from internal or external Processors/Adaptor/Main.

cargo-prosa is a utility to package and deliver a builded ProSA. This builder is packaged within cargo as a custom command to be well integrated with the Rust ecosystem.

Install

cargo-prosa is a Cargo subcommand, so you need to have Cargo installed to use it. Install cargo-prosa using the following command:

cargo install cargo-prosa

After installation, verify that the command is available and explore its features:

cargo prosa --help

Use

Let's create a ProSA. You'll see cargo-prosa commands are quite similar to cargo regarding project management.

cargo prosa new my-prosa
# or from an existing folder, init it
cargo prosa init

cargo-prosa is meant to evolve in the future. So maybe new things will be introduced. To update your model, you can update the generated file with cargo prosa update.

At this point you'll want to add componennts to your ProSA. To do so, you need to add crates that declare them into your Cargo.toml.

Once it's done, you can list all component avaible to build your ProSA with cargo prosa list. This will list all available component:

• Main - Main task (core::main::MainProc by default).
• TVF - Internal message format to use inside your ProSA (msg::simple_string_tvf::SimpleStringTvf by default).
• Processor/Settings - Processor and its associate settings.
• Adaptor - Adaptor related to the processor you want.

If you have different main/tvf, select them:

cargo prosa main MainProc
cargo prosa tvf SimpleStringTvf

Add your dependencies and your processor with its adaptor name

cargo add prosa
cargo prosa add -n stub-1 -a StubParotAdaptor stub

Once your ProSA is specified, the file ProSA.toml will contain the configuration. This file can be edited manually if you want.

Your project uses a build.rs/main.rs to create a binary that you can use.

Configuration

Keep in mind that you also need to have a settings file. A target/config.yml and target/config.toml will be generated when building.

But you can initiate a default one with:

cargo run -- -c default_config.yaml --dry_run

A configuration file contains:

• name: Name of your ProSA
• observability: Configuration of log/trace/metrics
• a map of processor name -> their settings

Run

When your ProSA is built, you can deploy like any Rust binary. So you'll find it in the target folder.

And you can run it:

cargo run -- -n "MyBuiltProSA" -c default_config.yaml
# or with binary
target/debug/my-prosa -n "MyBuiltProSA" -c default_config.yaml

Deploy

This builder offer you several possibilities to deploy your ProSA. The goal is to use the easiest method of a plateform to run your application.

Locally

On Linux or MacOS, you can install ProSA directly on your machine:

# Install ProSA
cargo prosa install

# Uninstall ProSA
cargo prosa uninstall

To avoid conflicts, specify a unique name during installation:

cargo prosa install --name dummy

Use the same name when uninstalling:

cargo prosa uninstall --name dummy

If the package isn't compiled for debug or release (--release), it will automatically compile during installation.

Simulate an installation with:

cargo prosa install --dry_run -n dummy

Linux

When you want to install ProSA with cargo prosa install:

$ cargo prosa install -r -n dummy
Creating service file OK
Copying binary OK
Generating configuration OK
Installed [12183 kB] ProSA `dummy`
Binary file : $HOME/.local/bin/prosa-dummy
Config file : $HOME/.config/prosa/dummy/prosa.toml
Service file: $HOME/.config/systemd/user/dummy.service

And you'll be able to handle it through systemctl:

$ systemctl --user status dummy.service
○ dummy.service - Local ProSA instance
     Loaded: loaded ($HOME/.config/systemd/user/dummy.service; disabled; preset: enabled)
     Active: inactive (dead)

To install it for the whole system, you can use the --system option:

$ sudo -E $HOME/.cargo/bin/cargo prosa install -r -s -n dummy
Creating service file OK
Copying binary OK
Generating configuration OK
Installed [12184 kB] ProSA `dummy`
Binary file : /usr/local/bin/prosa-dummy
Config file : /etc/prosa/dummy/prosa.toml
Service file: /etc/systemd/system/dummy.service

By installing ProSA system wide, you are able to see the service:

$ sudo service dummy status       
○ dummy.service - Local ProSA instance
     Loaded: loaded (/etc/systemd/system/dummy.service; disabled; preset: enabled)
     Active: inactive (dead)

MacOS

On MacOS it's the same as Linux, but with MacOS specifics.

So you can install it, and if the binary don't exist, it'll compil the project:

$ cargo prosa install -r -n dummy
Creating service OK
   Compiling ...
    Finished `release` profile [optimized] target(s) in 24.58s
Copying binary OK
Generating configuration OK
Installed [10578 kB] ProSA `dummy`
Binary file : $HOME/.local/bin/prosa-dummy
Config file : $HOME/.config/prosa/dummy/prosa.toml
Service file: $HOME/Library/LaunchAgents/com.prosa.dummy.plist

And once cargo-prosa installed the service, MacOS should notify you to indicate the new created service:

You can now load it and run it with:

launchctl load $HOME/Library/LaunchAgents/com.prosa.dummy.plist

and you can uninstall it with:

$ launchctl unload $HOME/Library/LaunchAgents/com.prosa.dummy.plist
$ cargo prosa uninstall -n dummy
Remove service OK
Remove binary OK
Uninstalled ProSA `dummy`
Binary file : $HOME/.local/bin/prosa-dummy
Config file : $HOME/.config/prosa/dummy/prosa.toml
Service file: $HOME/Library/LaunchAgents/com.prosa.dummy.plist

Container

Containerization will allow you to build and load ProSA in an image:

# Generate a Containerfile
cargo prosa container
# Generate a Dockerfile
cargo prosa container --docker

For your own needs, you can:

• Select from which image the container need to be build --image debian:stable-slim
• Along that you may have to specify the package manager use to install mandatory packages --package_manager apt
• If you want to compile ProSA through a builder, you can specify it with --builder rust:latest. A multi stage container file will be created.

Deb package

Deb package can be created with the cargo-deb crate.

To enable this feature, create, init or update your ProSA with the option --deb. It'll add every needed properties to generate a deb package.

The deb package will include the released binary, a default configuration file, and a systemd service file.

RPM package

RPM (Red Hat Package Manager) package can be created with the cargo-generate-rpm crate.

To enable this feature, create, init or update your ProSA with the option --rpm. It'll add every needed properties to generate an rpm package.

The rpm package will include the released binary, a default configuration file, and a systemd service file.