Skip to content
This repository has been archived by the owner on Jul 15, 2024. It is now read-only.

A hydroflow template project suitable for cargo-generate

Notifications You must be signed in to change notification settings

hydro-project/hydroflow-template

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

THIS REPOSITORY HAS BEEN MOVED INTO hydro-project/hydroflow

See here: https://github.com/hydro-project/hydroflow/tree/main/template/hydroflow#readme


Getting Started

This is a template for a Rust project that uses Hydroflow for distributed services. It implements a simple echo server and client over UDP.

Using the Template

cargo generate hydro-project/hydroflow-template

You will be prompted to name your project. Once the command completes, you can cd into the project and build the template.

cd <myproject>
cargo build

Running the Template

The server can be run in one terminal and one or more clients can be run in separate terminals.

Server

% cargo run -- --role server

Client

You can run multiple instances of the client by running the following command:

% cargo run -- --role client

Viewing Help

cargo run -- --help

Template Project Structure

The src directory contains the following files:

File Description
main.rs Contains main entry-point function for both client and server. Performs command-line argument parsing.
protocol.rs Contains the Message enum that defines the messages that can be sent between instances.
<role>.rs Contains the service for the given role. Example implementations and skeletal hydroflow spec are provided for server and client.
helpers.rs Contains helper functions that are invoked from Hydroflow code in multiple services.

Communication Patterns

No particular communication pattern is assumed by Hydroflow. The unmodified template application is designed to be used in a "star topology": multiple independent clients talking to a single server. However, the template can be easily modified to support other topologies. Additional examples are provided in the hydroflow repository in the hydroflow/examples directory.

Where do you go from here?

This template is intended to be a starting point for your own project. You'll undoubtedly want to change it.

In our experience, when starting a Hydroflow project we recommend a four-step approach:

  1. Roles: Identify the roles that your services will play (in the Opts struct in src/main.rs)
  2. Messages: Define the basic message types that services will send to each other (in the Message enum in src/protocol.rs).
  3. Print Received Messages: Utilize the template logic at each service that prints out messages received.
  4. Exercise Sending Patterns: Make sure the right messages get to the right recipients! Write simple logic to send out messages in all the message patterns you expect to see (in the src/<role>.rs files).
  5. Service Programming: Begin writing the actual logic for each service, with plenty of inspect(|m| println!("{:?}", m)) operators peppered throughout!

Have fun!

Print a Dataflow Graph

The client and server can optionally print out a dataflow graph of their hydroflow code.

Mermaid

Server

Run the following command and view the messages received by the server on stdout.

% cargo run -- --role server --graph mermaid

Client

Run the following command and type in the messages to send to the server. When the server responds, the echoed message will be printed on stdout.

% cargo run -- --role client --graph mermaid

Dot

Server

% cargo run -- --role server --graph dot

Client

% cargo run -- --role client --graph dot

About

A hydroflow template project suitable for cargo-generate

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages