greengrass-ipc
An unofficial, pure-Rust async client for AWS IoT Greengrass v2 on-device component IPC.
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'sSubscribeToIoTCore/PublishToIoTCore.
- Pure Rust. No C, no FFI, no
bindgen, no linking the AWS C SDK. Justtokio+aws-smithy-eventstreamfor 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 ;
use StreamExt;
async
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.
select!
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)
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
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
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.