feat: add CreateLocalDeployment IPC support (C + C++ + Rust)

Add CreateLocalDeployment operation to the C, C++, and Rust SDK, enabling
components to trigger local deployments via IPC without shelling out
to greengrass-cli.

Changes since initial review:
- Full schema: GgCreateLocalDeploymentArgs struct exposes all 6 fields
  (componentToConfiguration, rootComponentVersionsToAdd,
  rootComponentsToRemove, recipeDirectoryPath, artifactsDirectoryPath,
  failureHandlingPolicy)
- C++ wrapper: Client::create_local_deployment() added
- README: CreateLocalDeployment section with C/C++/Rust examples
- Mock packets: renamed ACCEPTED_HEADERS to RESPONSE_HEADERS per real
  IPC traces captured via GGLite-IPC-EventStream-Sniffer against
  Classic Nucleus v2.17.0
- Doc comments: clarified Classic vs Lite behavior (Lite has native
  support via ggdeploymentd, no Cli dep or ACL required)

Testing:
- nix flake check: 17/17 checks pass (formatting, namespacing,
  spelling, IWYU, C tests 45/45, Rust tests 28/28, cross-compile
  x86_64 + aarch64 + armv7l)
- Integration: cache-proxy-bridge/server/common all compile and pass
  172 tests with the updated SDK vendored in

Author: Mitchell

.cspell.json

@@ -13,6 +13,7 @@
     "**/CMakeLists.txt",
     "**/*.yml",
     "**/*.nix",
-    "**/iwyu_mappings.yml"
+    "**/iwyu_mappings.yml",
+    "design/**"
   ]
 }

.gitignore

@@ -8,3 +8,4 @@ result
 result-*
 compile_commands.json
 target/
+design/

README.md

@@ -31,6 +31,8 @@ The following Greengrass v2 IPC operations are currently supported by this SDK:
 - [UpdateThingShadow](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-updatethingshadow)
 - [DeleteThingShadow](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-deletethingshadow)
 - [ListNamedShadowsForThing](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-listnamedshadowsforthing)
+- [CreateLocalDeployment](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment)
+  > For other fields, use the generic `call()` method.
 
 ## Sample Greengrass Components
 

cpp/include/gg/ipc/client.hpp

@@ -22,6 +22,7 @@
 #include <utility>
 
 extern "C" {
+#include <gg/ipc/client.h>
 #include <gg/ipc/types.h>
 }
 
@@ -162,6 +163,23 @@ class Client {
     /// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-restartcomponent>
     std::error_code restart_component(std::string_view component_name) noexcept;
 
+    /// Create a local deployment on the core device.
+    /// Triggers a local deployment that can merge configuration into
+    /// components, add/remove root components, and specify local
+    /// recipe/artifact paths.
+    ///
+    /// On Classic Nucleus: requires a dependency on `aws.greengrass.Cli` and an
+    /// access-control policy allowing `aws.greengrass#CreateLocalDeployment`.
+    /// On Nucleus Lite: handled natively by ggdeploymentd — no dependency or
+    /// ACL required.
+    /// See:
+    /// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment>
+    std::error_code create_local_deployment(
+        const GgCreateLocalDeploymentArgs &args,
+        std::span<std::byte> deployment_id_mem = {},
+        std::string_view *deployment_id = nullptr
+    ) noexcept;
+
     /// Get component configuration value.
     /// Retrieves configuration for the specified key path.
     /// Pass empty span for complete config.

cpp/src/ipc/create_local_deployment.cpp

@@ -0,0 +1,35 @@
+// aws-greengrass-component-sdk - Lightweight AWS IoT Greengrass SDK
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#include <gg/ipc/client.hpp>
+#include <cstddef>
+#include <span>
+#include <string_view>
+#include <system_error>
+
+extern "C" {
+#include <gg/ipc/client.h>
+}
+
+namespace gg::ipc {
+
+std::error_code Client::create_local_deployment(
+    const GgCreateLocalDeploymentArgs &args,
+    std::span<std::byte> deployment_id_mem,
+    std::string_view *deployment_id
+) noexcept {
+    GgBuffer id_mem = { reinterpret_cast<uint8_t *>(deployment_id_mem.data()),
+                        deployment_id_mem.size() };
+    GgBuffer id_out = {};
+    auto err = ggipc_create_local_deployment(
+        &args, id_mem, deployment_id != nullptr ? &id_out : nullptr
+    );
+    if ((deployment_id != nullptr) && (err == GG_ERR_OK)) {
+        *deployment_id
+            = { reinterpret_cast<const char *>(id_out.data), id_out.len };
+    }
+    return err;
+}
+
+}

include/gg/ipc/client.h

@@ -116,6 +116,62 @@ GgError ggipc_update_state(GgComponentState state);
 /// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-restartcomponent>
 GgError ggipc_restart_component(GgBuffer component_name);
 
+/// Arguments for ggipc_create_local_deployment.
+/// All fields are optional; set GgObject fields to GG_OBJ_NULL and GgBuffer
+/// fields to (GgBuffer){0} when not used.
+typedef struct {
+    /// Map of component name → configuration merge map. Must be GG_TYPE_MAP
+    /// if provided (non-null).
+    GgObject component_to_configuration;
+    /// Map of component name → version string to add as root components.
+    /// Must be GG_TYPE_MAP if provided.
+    GgObject root_component_versions_to_add;
+    /// List of component name buffers to remove from root components.
+    /// Must be GG_TYPE_LIST if provided.
+    GgObject root_components_to_remove;
+    /// Path to a directory containing local recipe files.
+    GgBuffer recipe_directory_path;
+    /// Path to a directory containing local artifact files.
+    GgBuffer artifacts_directory_path;
+    /// Failure handling policy: "ROLLBACK" or "DO_NOTHING".
+    GgBuffer failure_handling_policy;
+} GgCreateLocalDeploymentArgs;
+
+/// Create a local deployment on the core device.
+/// Triggers a local deployment that can merge configuration into components,
+/// add/remove root components, and specify local recipe/artifact paths.
+///
+/// `args->component_to_configuration` — map whose keys are component names
+/// and whose values are maps of config to merge. Optional (set GG_OBJ_NULL
+/// to omit).
+/// `args->root_component_versions_to_add` — map of component name → version
+/// string to add as root components. Optional.
+/// `args->root_components_to_remove` — list of component name buffers to
+/// remove from root components. Optional.
+/// `args->recipe_directory_path` — path to local recipe directory. Optional.
+/// `args->artifacts_directory_path` — path to local artifact directory.
+/// Optional.
+/// `args->failure_handling_policy` — "ROLLBACK" or "DO_NOTHING". Optional.
+///
+/// If `deployment_id` is not NULL, on success it is populated with a view into
+/// `deployment_id_mem` holding the returned deployment id.
+/// `deployment_id_mem` must remain valid and unmodified while
+/// `deployment_id` is used.
+///
+/// On Classic Nucleus: requires a dependency on the `aws.greengrass.Cli`
+/// component and an `aws.greengrass.Cli` access-control policy allowing
+/// `aws.greengrass#CreateLocalDeployment`.
+/// On Nucleus Lite: CreateLocalDeployment is handled natively by ggdeploymentd
+/// — no Cli component dependency or ACL required.
+/// See:
+/// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment>
+ACCESS(read_write, 3)
+GgError ggipc_create_local_deployment(
+    const GgCreateLocalDeploymentArgs *args,
+    GgBuffer deployment_id_mem,
+    GgBuffer *deployment_id
+);
+
 /// Get component configuration value.
 /// Retrieves configuration for the specified key path.
 /// Pass empty list for complete config.

misc/dictionary.txt

@@ -10,6 +10,7 @@ ffat
 fileb
 flto
 fstrict
+ggdeploymentd
 ggipc
 greengrassv2
 idents

mock/gg/ipc/packet_sequences.h

@@ -84,6 +84,22 @@ GgipcPacketSequence gg_test_restart_component_error_sequence(
     int32_t stream_id, GgBuffer component_name
 );
 
+GgipcPacketSequence gg_test_create_local_deployment_accepted_sequence(
+    int32_t stream_id,
+    GgObject component_to_configuration,
+    GgBuffer deployment_id
+);
+
+GgipcPacketSequence gg_test_create_local_deployment_error_sequence(
+    int32_t stream_id, GgObject component_to_configuration
+);
+
+GgipcPacketSequence gg_test_create_local_deployment_versions_accepted_sequence(
+    int32_t stream_id,
+    GgObject root_component_versions_to_add,
+    GgBuffer deployment_id
+);
+
 // Shadow sequences
 
 GgipcPacketSequence gg_test_shadow_update_accepted_sequence(

mock/packets/component_packet_sequences.c

@@ -114,3 +114,101 @@ GgipcPacketSequence gg_test_restart_component_error_sequence(
         .len = 2
     };
 }
+
+GgipcPacket gg_test_create_local_deployment_request_packet(
+    int32_t stream_id, GgObject component_to_configuration
+) {
+    static GgKV payload[1];
+    payload[0]
+        = gg_kv(GG_STR("componentToConfiguration"), component_to_configuration);
+    size_t payload_len = sizeof(payload) / sizeof(payload[0]);
+
+    return (GgipcPacket) { .direction = CLIENT_TO_SERVER,
+                           .has_payload = true,
+                           .payload = gg_obj_map((GgMap) {
+                               .pairs = payload, .len = payload_len }),
+                           .headers = GG_IPC_REQUEST_HEADERS(
+                               stream_id, "aws.greengrass#CreateLocalDeployment"
+                           ),
+                           .header_count = GG_IPC_REQUEST_HEADERS_COUNT };
+}
+
+GgipcPacket gg_test_create_local_deployment_response_packet(
+    int32_t stream_id, GgBuffer deployment_id
+) {
+    static GgKV payload[1];
+    payload[0] = gg_kv(GG_STR("deploymentId"), gg_obj_buf(deployment_id));
+    size_t payload_len = sizeof(payload) / sizeof(payload[0]);
+
+    return (GgipcPacket) { .direction = SERVER_TO_CLIENT,
+                           .has_payload = true,
+                           .payload = gg_obj_map((GgMap) {
+                               .pairs = payload, .len = payload_len }),
+                           .headers = GG_IPC_ACCEPTED_HEADERS(
+                               stream_id, "aws.greengrass#CreateLocalDeployment"
+                           ),
+                           .header_count = GG_IPC_ACCEPTED_HEADERS_COUNT };
+}
+
+GgipcPacketSequence gg_test_create_local_deployment_accepted_sequence(
+    int32_t stream_id,
+    GgObject component_to_configuration,
+    GgBuffer deployment_id
+) {
+    return (GgipcPacketSequence) {
+        .packets = { gg_test_create_local_deployment_request_packet(
+                         stream_id, component_to_configuration
+                     ),
+                     gg_test_create_local_deployment_response_packet(
+                         stream_id, deployment_id
+                     ) },
+        .len = 2
+    };
+}
+
+GgipcPacketSequence gg_test_create_local_deployment_error_sequence(
+    int32_t stream_id, GgObject component_to_configuration
+) {
+    return (GgipcPacketSequence) {
+        .packets = { gg_test_create_local_deployment_request_packet(
+                         stream_id, component_to_configuration
+                     ),
+                     gg_test_ipc_permissions_error_packet(stream_id) },
+        .len = 2
+    };
+}
+
+GgipcPacket gg_test_create_local_deployment_versions_request_packet(
+    int32_t stream_id, GgObject root_component_versions_to_add
+) {
+    static GgKV payload[1];
+    payload[0] = gg_kv(
+        GG_STR("rootComponentVersionsToAdd"), root_component_versions_to_add
+    );
+    size_t payload_len = sizeof(payload) / sizeof(payload[0]);
+
+    return (GgipcPacket) { .direction = CLIENT_TO_SERVER,
+                           .has_payload = true,
+                           .payload = gg_obj_map((GgMap) {
+                               .pairs = payload, .len = payload_len }),
+                           .headers = GG_IPC_REQUEST_HEADERS(
+                               stream_id, "aws.greengrass#CreateLocalDeployment"
+                           ),
+                           .header_count = GG_IPC_REQUEST_HEADERS_COUNT };
+}
+
+GgipcPacketSequence gg_test_create_local_deployment_versions_accepted_sequence(
+    int32_t stream_id,
+    GgObject root_component_versions_to_add,
+    GgBuffer deployment_id
+) {
+    return (GgipcPacketSequence) {
+        .packets = { gg_test_create_local_deployment_versions_request_packet(
+                         stream_id, root_component_versions_to_add
+                     ),
+                     gg_test_create_local_deployment_response_packet(
+                         stream_id, deployment_id
+                     ) },
+        .len = 2
+    };
+}

mock/packets/packets.h

@@ -165,6 +165,18 @@ GgipcPacket gg_test_restart_component_response_packet(
     int32_t stream_id, GgBuffer restart_status
 );
 
+GgipcPacket gg_test_create_local_deployment_request_packet(
+    int32_t stream_id, GgObject component_to_configuration
+);
+
+GgipcPacket gg_test_create_local_deployment_response_packet(
+    int32_t stream_id, GgBuffer deployment_id
+);
+
+GgipcPacket gg_test_create_local_deployment_versions_request_packet(
+    int32_t stream_id, GgObject root_component_versions_to_add
+);
+
 // Shadow operations
 
 GgipcPacket gg_test_shadow_update_request_packet(