greengrass-ipc 0.2.0

Unofficial pure-Rust async client for AWS IoT Greengrass v2 on-device component IPC (nucleus IPC over the Unix domain socket).
Documentation

greengrass-ipc

An unofficial, pure-Rust async client for AWS IoT Greengrass v2 on-device component IPC.

CI Crates.io Docs.rs License

A pure-Rust, async client for the AWS IoT Greengrass v2 component IPC service — the on-device Unix-domain-socket API that Greengrass components use to talk to the Greengrass nucleus.

⚠️ Unofficial. Not affiliated with, endorsed by, or sponsored by Amazon. "AWS", "AWS IoT", and "Greengrass" are used descriptively to say what this interoperates with.

🔗 Built with this: nucleus-job-plugin — an AWS IoT Jobs runner that reaches IoT Core through the nucleus via this crate's SubscribeToIoTCore / PublishToIoTCore.

  • Pure Rust. No C, no FFI, no bindgen, no linking the AWS C SDK. Just tokio + aws-smithy-eventstream for the frame codec.
  • Async-first, ergonomic, typed operations.
  • IPC calls are safe from anywhere — including from inside a subscription's event loop. (The official AWS C SDK forbids making IPC calls from within subscription callbacks; this crate does not.)
  • Implements the operations the official Rust binding is missing — notably SubscribeToComponentUpdates, DeferComponentUpdate, PauseComponent, ResumeComponent.

Unofficial. This project is community-maintained and is not affiliated with, endorsed by, or sponsored by Amazon. "AWS", "IoT Greengrass", and related marks belong to Amazon; they are used here only to describe compatibility.

Status

Early development. The API surface is being built in tiers. Tier 1 (component lifecycle + update management, local pub/sub, configuration) and Tier 2 (AWS IoT Core MQTT pub/sub) are implemented.

Example

use greengrass_ipc::{Client, LifecycleState};
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connects using the SVCUID + socket path env vars the nucleus injects.
    let client = Client::connect_from_env().await?;

    // Report the component healthy.
    client.update_state(LifecycleState::Running).await?;

    // React to deployments, and defer them while we're busy.
    let mut updates = client.subscribe_to_component_updates().await?;
    while let Some(event) = updates.next().await {
        if let Some(pre) = event?.pre_update_event {
            // Safe to call IPC from right here:
            client
                .defer_component_update(pre.deployment_id, Some(30_000), None)
                .await?;
        }
    }
    Ok(())
}

Connection lifecycle: exit, don't reconnect

The nucleus issues every component a fresh SVCUID each time it starts that component. A running process only ever sees the token it was exec'd with, and the environment of a live process never changes — so once the connection drops, that process can no longer authenticate.

Client::connect_from_env() re-reads the environment, which makes a reconnect loop look reasonable. It isn't: after a nucleus restart it retries with a token the nucleus no longer honours, and fails forever.

The correct response to a lost connection is to exit. The nucleus restarts its components on the way back up, and the replacement gets a valid token.

tokio::select! {
    _ = client.closed() => {
        eprintln!("nucleus IPC lost; exiting so the nucleus can restart us with a fresh token");
        std::process::exit(1);
    }
    result = your_work(&client) => result?,
}

Client::closed() resolves when the connection is lost, so you notice even with no operation in flight — a component that only publishes occasionally would otherwise not find out until its next call.

Lingering is not merely useless, it can be actively harmful: a process holding an exclusive resource — a serial port opened with TIOCEXCL, a lock file, a listening socket — will block its own replacement from starting. We hit exactly that in practice: an orphaned component kept a USB scanner open, and the nucleus's replacement went BROKEN with EBUSY until the orphan was killed by hand.

Try it against a real Greengrass nucleus (Docker, bring only AWS creds)

cd examples/docker
cp .env.example .env                                   # set AWS_REGION
cp greengrass-v2-credentials/credentials.example \
   greengrass-v2-credentials/credentials               # add your AWS keys
./run-demo.sh                                          # provisions + deploys a demo component
./teardown.sh                                          # cleans up

Spins up the official Greengrass nucleus in Docker (auto-provisioned), builds a tiny component that uses this crate from crates.io, deploys it locally, and shows it reach RUNNING. See examples/docker/ — note it creates billable AWS resources; always run the teardown. (No AWS account? The examples/ run offline with cargo run --example ….)

Why this exists

The only pre-existing Rust option is AWS's official aws-greengrass-component-sdk (crate gg_sdk), which is a C library with thin Rust FFI bindings: it needs clang/bindgen, is effectively Linux-only, and omits several IPC operations (forcing consumers into a fragile generic escape hatch, which also rejects IPC calls made from inside subscription callbacks). greengrass-ipc is a from-scratch pure-Rust alternative.

Supported operations

Being implemented in tiers (of the ~34 Greengrass IPC operations). Currently: component lifecycle & update management (UpdateState, SubscribeToComponentUpdates, DeferComponentUpdate, Pause/Resume/RestartComponent), configuration (Get/UpdateConfiguration, SubscribeToConfigurationUpdate), local pub/sub (Publish/SubscribeToTopic), and AWS IoT Core MQTT pub/sub (Publish/SubscribeToIoTCore).

The EventStream RPC wire protocol (framing, the Connect handshake, headers) is documented in docs/WIRE_PROTOCOL.md.

Minimum Supported Rust Version (MSRV)

Rust 1.94.1. MSRV bumps are treated as minor version changes.

License

Licensed under either of

at your option.

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.