README.md

Websocket Relay

Description

An example application that connects to a homestar-runtime node over a websocket connection in order to run static Wasm-based, image processing workflows that chain inputs and outputs using inlined promises.

This application demonstrates:

• workflows built using the @fission-codes/homestar client library
• websocket notifications of UCAN Invocation Receipts sent between a web client and a homestar runner using @fission-codes/homestar
• instantaneous replay of previously run, cached executions
• fetching content (the original static image) over IPFS through a local blockstore
• the WIT + IPLD interpreter for Wasm(time) embedded execution within a homestar runner

Install

Nix

If you're using our Nix file, you get these installs for free.

Manual

To get started, please install:

• Rust, unless you're running homestar as a binary
• Node & NPM
• Kubo IPFS

Usage

1. Run cargo run to start the runtime and an IPFS daemon as a background process. This runtime includes ANSI-coded logging by default.

2. In a separate terminal window, run npm install --prefix relay-app to install dependencies and npm run --prefix relay-app dev to start the relay web application (UI) on http://localhost:5173/ by default.

3. Press the play buttons on the UI to run workflows. Follow along with this video for more information.

   https://www.loom.com/share/b0f882adc2ea45709d1f3031b5e61e92?sid=29cb403e-c666-4753-82f5-e35bbb710151

Following along with the video, once you're up and running on localhost, you'll see two workflows with several tasks. You can click on the stack icon on the top right hand corner to inspect the source of the workflows.

Running the first workflow completes a number of image-processing tasks, i.e. crop -> rotate90 -> blur, submitting the rendered output to each subsequent task.

The second workflow executes crop -> rotate90 as well, and then something new: grayscale. As demonstrated, the first two task executions can be skipped if they've been previously run.

Tips & Common Issues

• On macOS, for example, a simple homebrew install would install everything you need: brew install rust npm ipfs.

• Running homestar using cargo run requires a minimum Rust version of 1.75.0. If you've got an older version of rust, update it with rustup update.

• You do not have to start Kubo (IPFS) on your own. The example will do this for you, and use examples/websocket-relay/tmp/.ipfs as a local blockstore. Feel free to discard it when you don't need it.

• If you're already running an IPFS instance, for example IPFS Desktop, the application will check for it and not start a new, local one. However, the application expects a default IPFS host and port. The expected IPFS host and port can be updated in the homestar network settings:

  [node]
  
  [node.network.ipfs]
  host = "127.0.0.1"
  port = 5001

• We have officially packaged homestar binaries using brew, so brew install fission-codes/fission/homestar will install mostly everything you need, including ipfs. You will still need npm to run this example, and you'll have to manually ipfs add the synthcat.png and example_test.wasm files located in this directory. Then, from this folder, you can run the example like this:

  homestar start --db homestar.db
  

  Afterward, run npm install --prefix relay-app to install dependencies and npm run --prefix relay-app dev to start the relay web application (UI) on http://localhost:5173/ by default.