homestar

_{⚠️ Work in progress ⚠️}

Outline

Workspace
Testing the Project
Running the Runtime on Docker
Contributing
Getting Help
External Resources
License

Workspace

This repository is comprised of a few library packages and a binary that represents the homestar runtime.

Core Crates

homestar-core

The core library implements much of the Ucan Invocation and Ipvm Workflow specifications and is used as the foundation for other packages in this workspace and within the runtime engine.
homestar-wasm

This wasm library manages the wasmtime runtime, provides the Ipld to/from Wit interpreter/translation-layer, and implements the input interface for working with Ipvm's standard Wasm tasks.

Runtime Crate

homestar-runtime

The runtime is responsible for bootstrapping and running nodes, scheduling and executing workflows as well as tasks within workflows, handling retries and failure modes, etc.

Non-published, Helper Crates

homestar-functions

Currently, this is a helper and example crate for writing and compiling Wasm components using wit-bindgen.

It will be expanded upon as a default set of Wasm mods and functions.

Testing the Project

Running the tests:

We recommend using cargo nextest, which is installed by default in our Nix flake or can be installed separately.

cargo nextest run --all-features --no-capture

The above command translates to this using the default cargo test:

cargo test --all-features -- --nocapture

Running the Runtime on Docker

We recommend setting your [Docker Engine][docker-engine] configuration with experimental and buildkit set to true, for example:

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": true,
  "features": {
    "buildkit": true
  }
}

Build a multi-plaform Docker image via buildx:

docker buildx build --file docker/Dockerfile --platform=linux/amd64,linux/arm64 -t homestar-runtime --progress=plain .

Run a Docker image (depending on your platform):

docker run --platform=linux/arm64 -t homestar-runtime

Contributing

🎈 We're thankful for any feedback and help in improving our project! We have a contributing guide to help you get involved. We also adhere to our Code of Conduct.

Nix

This repository contains a Nix flake that initiates both the Rust toolchain set in rust-toolchain.toml and a pre-commit hook. It also installs external dependencies, as well as helpful cargo binaries for development. Please install nix and direnv to get started.

Run nix develop or direnv allow to load the devShell flake output, according to your preference.

Formatting

For formatting Rust in particular, we automatically format on nightly, as it uses specific nightly features we recommend by default.

Pre-commit Hook

This project recommends using pre-commit for running pre-commit hooks. Please run this before every commit and/or push.

If you are doing interim commits locally, and for some reason if you don't want pre-commit hooks to fire, you can run git commit -a -m "Your message here" --no-verify.

Recommended Development Flow

We recommend leveraging cargo-watch, cargo-expand and irust for Rust development.
We also recommend using cargo-udeps for removing unused dependencies before commits and pull-requests.
If using our Nix flake, there are a number of handy command shortcuts available for working with cargo-watch, diesel, and other items, including:
- ci, which runs a sequence of commands to check formatting, lints, release builds, and tests
- db and db-reset for running diesel setup and migrations
- doc for generating cargo docs with private-items documented
- compile-wasm for compiling homestar-functions, a wit-bindgen-driven example, to the wasm32-unknown-unknown target
- docker-<amd64,arm64> for running docker builds
- nx-test, which translates to cargo nextest run && cargo test --doc
- x-test for testing continuously as files change, translating to cargo watch -c -s "cargo nextest run && cargo test --doc"
- x-<build,check,run,clippy> for running a variety of cargo watch execution stages
- nx-test-<all,0>, which is just like nx-test, but adds all or 0 for running tests either with the all-features flag or no-default-features flag, respectively
- x-<build,check,run,clippy,test>-<core,wasm,runtime> for package-specific builds, tests, etc.

Conventional Commits

This project lightly follows the Conventional Commits convention to help explain commit history and tie in with our release process. The full specification can be found here. We recommend prefixing your commits with a type of fix, feat, docs, ci, refactor, etc..., structured like so:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Getting Help

For usage questions, usecases, or issues reach out to us in our Discord channel.

We would be happy to try to answer your question or try opening a new issue on Github.

External Resources

What Is An IPVM
IPVM: High-Level Spec
Contributing Research
Seamless Services for an Open World by Brooklyn Zelenka
Foundations for Open-World Compute by Zeeshan Lakhani
IPVM: The Long-Fabled Execution Layer by Brooklyn Zelenka
IPVM - IPFS and WASM by Brooklyn Zelenka
Breaking Down the Interplanetary Virtual Machine
Ucan Invocation Spec
Wasm/Wit Demo - Februrary 2023 by Zeeshan Lakhani

License

This project is licensed under the Apache License 2.0, or http://www.apache.org/licenses/LICENSE-2.0.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

bmann/homestar