Skip to main content

Rust

This page covers advanced options for writing serverless functions in Rust.

Including the Satellite​

After defining your Functions, at the very end of your lib.rs module, include the Satellite to ensure that your custom logic and the default features or Juno are properly registered and executable within the Juno ecosystem.

important

This is crucial for compatibility with the Juno Console and CLI, as it expects the Satellite to expose the necessary functionality for monitoring, deployment, and interaction. Without this macro, certain features in the Console may not function correctly.

include_satellite!();

Feature Selection​

When you run juno functions eject, all the available hooks and assertions are scaffolded in your lib.rs module. However, if you don’t have to implement all of them for example to improve readability or reduce unnecessary logic, you can selectively enable only the features you need.

To do this, disable the default features in your Cargo.toml and explicitly specify only the ones you want to use.

For example, if you only need on_set_doc and assert_set_doc, configure your Cargo.toml like this:

[dependencies]
junobuild-satellite = { version = "0.0.21", default-features = false, features = ["on_set_doc", "assert_set_doc"] }

With this setup, only on_set_doc and assert_set_doc must be implemented with custom logic, while other hooks and assertions will not be included in your Satellite.

Upgrade​

After deployment, keeping your Satellite functional and optimized requires ongoing monitoring and updates. Staying up to date is also a key factor, as we may introduce new features that need to be integrated into your Satellite to ensure full functionality within the Juno Console.

Since your project includes all Satellite features using include_satellite!();, it's essential to stay in sync with Juno's updates to maintain compatibility.

Important

If your Satellite includes custom serverless functions, do not upgrade through the Juno Console. The Console upgrade replaces your Satellite with the stock version, which would overwrite your custom code.

When the Console notifies you of a new version, use it as a reminder to update your dependencies and redeploy your custom build, as described below.

What to do​

To upgrade your Satellite, bump the dependencies in your Cargo.toml file located in /src/satellite/. The key dependencies to check and update are:

  • junobuild-satellite
  • junobuild-storage
  • junobuild-macros
  • ic_cdk
  • candid

If other crates in your project depend on these, they should also be upgraded accordingly.

Once updated, build your functions and redeploy using the CLI or the GitHub Actions flow.

👉 Check the Crate Versions reference page for the exact versions to use.

If you need assistance, feel free to reach out through the available support channels.

caution

Always upgrade iteratively and avoid skipping version numbers. While we strive to minimize breaking changes, it's crucial to upgrade through each released version sequentially.

For example, if you're on v0.0.23 and the latest release is v0.0.26, first upgrade to v0.0.24, then v0.0.25, and finally v0.0.26. Skipping versions could lead to unexpected issues.

Versioning​

Every Satellite that runs your serverless functions includes a version number, defined in the Cargo.toml file of your project:

[package]
name = "satellite"
version = "0.1.0"

This version is embedded into the compiled Wasm binary and displayed in the Juno Console. It helps you:

  • Track which version of your serverless logic is currently deployed.
  • Debug more effectively by matching behavior in the Console with specific code versions.
  • Move independently of Juno updates — you're in full control of your own function versioning.

You can use any versioning scheme that suits your development workflow (e.g. 0.1.0, 1.0.0-beta, 2025.04.18...).

Additional Notes​

WebAssembly (Wasm) binaries serve as the compilation target for the Satellites. While Juno's CLI automatically specifies this target for you, manual execution of certain cargo commands necessitates explicitly providing this target.

For instance:

cargo clippy --target=wasm32-unknown-unknown