https://github.com/ipvm-wg/homestar

Homestar is the individual node that makes up the Everywhere Computer network (similar to how IPFS Kubo, Iroh, Nabu, or other implementation nodes make up the IPFS network). It's written in Rust and is designed for performance and composability.
https://github.com/ipvm-wg/homestar

compute fission ipvm rust wasm wit workflows

Last synced: 6 days ago
JSON representation

Homestar is the individual node that makes up the Everywhere Computer network (similar to how IPFS Kubo, Iroh, Nabu, or other implementation nodes make up the IPFS network). It's written in Rust and is designed for performance and composability.

• Host: GitHub
• URL: https://github.com/ipvm-wg/homestar
• Owner: ipvm-wg
• License: apache-2.0
• Created: 2022-12-07T05:54:56.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-09-26T17:11:35.000Z (3 months ago)
• Last Synced: 2024-11-29T12:02:40.420Z (14 days ago)
• Topics: compute, fission, ipvm, rust, wasm, wit, workflows
• Language: Rust
• Homepage: https://docs.everywhere.computer/homestar/what-is-homestar/
• Size: 19.7 MB
• Stars: 219
• Watchers: 15
• Forks: 24
• Open Issues: 80
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS
  • Security: SECURITY.md

Awesome Lists containing this project

• awesome-starred - ipvm-wg/homestar - 💫 The IPVM reference implementation (rust)

README

        


  

    

  


  
Homestar


  


    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

    

      

    

  



##

## Outline

- [Quickstart](#quickstart)

- [Packages](#packages)

- [Running Examples](#running-examples)

- [Workspace](#workspace)

- [Contributing](#contributing)

- [Releases and Builds](#releases-and-builds)

- [Getting Help](#getting-help)

- [External Resources](#external-resources)

- [License](#license)

## Quickstart

If you're looking to help develop `Homestar`, please dive right into our

[development](./DEVELOPMENT.md) guide.

Otherwise, the easiest way to get started and see `Homestar` in action is to

follow-along with our [examples](./examples). To start, try out our

image-processing [websocket relay](./examples/websocket-relay) example, which

integrates `Homestar` with a browser application to run a

statically-configured workflow. The associated `README.md` walks through

what to install (i.e. `rust`, `node/npm`, `ipfs`), what commands

to run, and embeds a video demonstrating its usage.

Throughout the `Homestar` ecosystem and documentation, we'll draw a distinction

between the [host runtime][host-runtime] and the support for different

[guest languages and bindings][guest].

If you're mainly interested in learning how to write and build-out Wasm

components (currently focused on authoring in Rust), please jump into

our [`homestar-functions`](./homestar-functions) directory and check out

our examples there.

## Packages

Each `Homestar` release will also build packages for distribution across

different platforms.

- [homebrew][homebrew]: `brew install fission-codes/fission/homestar`

  This includes `ipfs` in the install by default.

- [npm](https://www.npmjs.com/package/homestar-runtime): `npm install homestar-runtime -g` Wraps the `homestar-runtime` binary in a node script.

## Running Examples

All [examples](./examples) contain instructions for running

them, including what to install and how to run them. Please clone this repo,

and get started!

Each example showcases something specific and interesting about `Homestar`

as a system.

Our current list includes:

- [websocket relay](./examples/websocket-relay/README.md) - An example

  (browser-based) application that connects to the `homestar-runtime` over a

  WebSocket connection in order to run a couple static Wasm-based, image

  processing workflows that chain inputs and outputs.

## Workspace

This repository is comprised of a few library packages and a library/binary that

represents the `Homestar` runtime. We recommend diving into each package's own

`README.md` for more information when available.

### Core Crates

- [homestar-invocation](./homestar-invocation)

  The *invocation* library implements much of the [Ucan Invocation][ucan-invocation]

  specification and is used as the foundation for other packages in this

  `workspace` and within the runtime engine.

- [homestar-wasm](./homestar-wasm)

  This *wasm* library manages the [wasmtime][wasmtime] runtime, provides the

  [IPLD][ipld] to/from [WIT][wit] interpreter/translation-layer, and implements

  the input interface for working with Ipvm's standard Wasm tasks.

  You can find the spec for translating between IPLD and WIT runtime values

  based on WIT types [here](./homestar-wasm/README.md#interpreting-between-ipld-and-wit).

  *Note*: This library also includes a [WIT `world`][wa.dev-homestar-host] for

  bindings implemented on the host runtime.

- [homestar-workflow](./homestar-workflow)

  The *workflow* library implements workflow-centric [Ipvm features][ipvm-spec]

  and is used as the foundation for other packages in this `workspace` and

  within the runtime engine.

### Runtime Crate

- [homestar-runtime](./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 Crates

- [homestar-functions/*](./homestar-functions)

  `homestar-functions` is a directory of helper, test, and example crates for

  writing and compiling [Wasm component][wasm-component] modules using

  [wit-bindgen][wit-bindgen].

  You can find our component packages on [wa.dev][wa.dev-homestar].

- [homestar-schemas](./homestar-schemas)

`homestar-schemas` is a crate for generating OpenRPC docs and JSON Schemas that document the [homestar-runtime](./homestar-runtime) JSON-RPC API, workflows, and receipts.

- [examples/*](./examples)

  `examples` contains examples and demos showcasing `Homestar` packages

  and the `Homestar` runtime. Each example is set up as its own crate,

  demonstrating the necessary dependencies and setup(s).

## Contributing

:balloon: We're thankful for any feedback and help in improving our project!

We have a focused [development](./DEVELOPMENT.md) guide, as well as a

more general [contributing](./CONTRIBUTING.md) guide to help you get involved.

We always adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md).

## Releases and Builds

### Crates, Tags, and GitHub Releases

Homestar uses [release-plz][release-plz] to publish [crates][rel-crates],

[tags][rel-tags], changelogs, and [GitHub Releases][rel-gh]. Upon merging,

a `release-plz` bot PR, four crates are continuously published,

**all tied to the same cargo version currently** (though this may change in the

future):

- [homestar-runtime][crate-runtime]

- [homestar-invocation][crate-invocation]

- [homestar-workflow][crate-workflow]

- [homestar-wasm][crate-wasm]

### Build Targets

Every [GitHub release of the homestar-runtime][rel-latest] contains build assets

for running the `homestar-runtime` on different target architectures, as well as

[DEB][deb] and [RPM][rpm] packages (tagged with the architectured they were

compiled for). Our homebrew package for the runtime is also tied to releases

and can be installed with `brew install fission-codes/fission/homestar`.

We also leverage [cross][cross-rs] for [locally cross-compiling](./Cross.toml)

to varying Linux and Apple target platforms.

### NPM Packages

We also release some of our cross-compiled runtime binaries as

[npm binary packages](./homestar-runtime/npm/README.md):

- [homestar-runtime](https://www.npmjs.com/package/homestar-runtime) - This is

  the main package that installs the os specific binary package and runs it.

- [homestar-darwin-arm64](https://www.npmjs.com/package/homestar-darwin-arm64)

- [homestar-darwin-x64](https://www.npmjs.com/package/homestar-darwin-x64)

- [homestar-linux-arm64](https://www.npmjs.com/package/homestar-linux-arm64)

- [homestar-linux-x64](https://www.npmjs.com/package/homestar-linux-x64)

- [homestar-windows-x64](https://www.npmjs.com/package/homestar-windows-x64)

## Getting Help

For usage questions, usecases, or issues reach out to us in our [Discord channel](https://fission.codes/discord).

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-wg]

- [IPVM: High-Level Spec][ipvm-spec]

- [Contributing Research][research]

- [Seamless Services for an Open World][seamless-services] by Brooklyn Zelenka

- [Foundations for Open-World Compute][foundations-for-openworld-compute] by Zeeshan Lakhani

- [IPVM: The Long-Fabled Execution Layer][cod-ipvm] by Brooklyn Zelenka

- [IPVM - IPFS and WASM][ipfs-thing-ipvm] by Brooklyn Zelenka

- [Breaking Down the Interplanetary Virtual Machine][blog-1]

- [Ucan Invocation Spec][ucan-invocation]

## License

This project is licensed under the [Apache License 2.0](./LICENSE), or

[http://www.apache.org/licenses/LICENSE-2.0][apache].

### 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.

[apache]: https://www.apache.org/licenses/LICENSE-2.0

[blog-1]: https://fission.codes/blog/ipfs-thing-breaking-down-ipvm/

[cod-ipvm]: https://www.youtube.com/watch?v=3y1RB8wt_YY

[crate-runtime]: https://crates.io/crates/homestar-runtime

[crate-invocation]: https://crates.io/crates/homestar-invocation

[crate-workflow]: https://crates.io/crates/homestar-workflow

[crate-wasm]: https://crates.io/crates/homestar-wasm

[cross-rs]: https://github.com/cross-rs/cross

[deb]: https://www.debian.org/doc/manuals/debian-faq/pkg-basics.en.html

[demo-1]: https://www.loom.com/share/3204037368fe426ba3b4c952b0691c5c

[foundations-for-openworld-compute]: https://youtu.be/dRz5mau6fsY

[guest]: https://github.com/bytecodealliance/wit-bindgen#supported-guest-languages

[homebrew]: https://brew.sh/

[host-runtime]: https://github.com/bytecodealliance/wit-bindgen#host-runtimes-for-components

[ipfs-thing-ipvm]: https://www.youtube.com/watch?v=rzJWk1nlYvs

[ipld]: https://ipld.io/

[ipvm-spec]: https://github.com/ipvm-wg/spec

[ipvm-wg]: https://github.com/ipvm-wg

[ipvm-workflow-spec]: https://github.com/ipvm-wg/workflow

[mit]: http://opensource.org/licenses/MIT

[rel-crates]: https://crates.io/search?q=homestar

[rel-gh]: https://github.com/ipvm-wg/homestar/releases

[rel-latest]: https://github.com/ipvm-wg/homestar/releases/latest

[rel-tags]: https://github.com/ipvm-wg/homestar/tags

[release-plz]: https://release-plz.ieni.dev/

[rpm]: https://rpm.org/

[research]: https://github.com/ipvm-wg/research

[seamless-services]: https://youtu.be/Kr3B3sXh_VA

[ucan-invocation]: https://github.com/ucan-wg/invocation

[wa.dev-homestar]: https://wa.dev/homestar

[wa.dev-homestar-host]: https://wa.dev/homestar:host

[wasm-component]: https://github.com/WebAssembly/component-model

[wasmtime]: https://github.com/bytecodealliance/wasmtime

[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md

[wit-bindgen]: https://github.com/bytecodealliance/wit-bindgen