Skip to content

Commit e40c91a

Browse files
author
Mitchell
committed
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
1 parent 494a597 commit e40c91a

13 files changed

Lines changed: 685 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ The following Greengrass v2 IPC operations are currently supported by this SDK:
3131
- [UpdateThingShadow](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-updatethingshadow)
3232
- [DeleteThingShadow](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-deletethingshadow)
3333
- [ListNamedShadowsForThing](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-shadows.html#ipc-operation-listnamedshadowsforthing)
34+
- [CreateLocalDeployment](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment)
3435

3536
## Sample Greengrass Components
3637

‎cpp/include/gg/ipc/client.hpp‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
#include <utility>
2323

2424
extern "C" {
25+
#include <gg/ipc/client.h>
2526
#include <gg/ipc/types.h>
2627
}
2728

@@ -162,6 +163,18 @@ class Client {
162163
/// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-restartcomponent>
163164
std::error_code restart_component(std::string_view component_name) noexcept;
164165

166+
/// Create a local deployment on the core device.
167+
/// Triggers a local deployment that can merge configuration into
168+
/// components, add/remove root components, and specify local
169+
/// recipe/artifact paths to overwrite the Greengrass recipe/artifact
170+
/// stores. See:
171+
/// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment>
172+
std::error_code create_local_deployment(
173+
const GgCreateLocalDeploymentArgs &args,
174+
std::span<std::byte> deployment_id_mem = {},
175+
std::string_view *deployment_id = nullptr
176+
) noexcept;
177+
165178
/// Get component configuration value.
166179
/// Retrieves configuration for the specified key path.
167180
/// Pass empty span for complete config.

‎cpp/src/ipc/create_local_deployment.cpp‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// aws-greengrass-component-sdk - Lightweight AWS IoT Greengrass SDK
2+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
// SPDX-License-Identifier: Apache-2.0
4+
5+
#include <gg/ipc/client.hpp>
6+
#include <cstddef>
7+
#include <span>
8+
#include <string_view>
9+
#include <system_error>
10+
11+
extern "C" {
12+
#include <gg/ipc/client.h>
13+
}
14+
15+
namespace gg::ipc {
16+
17+
std::error_code Client::create_local_deployment(
18+
const GgCreateLocalDeploymentArgs &args,
19+
std::span<std::byte> deployment_id_mem,
20+
std::string_view *deployment_id
21+
) noexcept {
22+
GgBuffer id_buf = { reinterpret_cast<uint8_t *>(deployment_id_mem.data()),
23+
deployment_id_mem.size() };
24+
auto err = ggipc_create_local_deployment(
25+
&args, deployment_id != nullptr ? &id_buf : nullptr
26+
);
27+
if ((deployment_id != nullptr) && (err == GG_ERR_OK)) {
28+
*deployment_id
29+
= { reinterpret_cast<const char *>(id_buf.data), id_buf.len };
30+
}
31+
return err;
32+
}
33+
34+
}

‎cpp/test/client/create_local_deployment.cpp‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
// aws-greengrass-component-sdk - Lightweight AWS IoT Greengrass SDK
2+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
// SPDX-License-Identifier: Apache-2.0
4+
5+
#include <gg/ipc/client.hpp>
6+
#include <gg/object.hpp>
7+
#include <cstddef>
8+
#include <cstdint>
9+
#include <array>
10+
#include <span>
11+
#include <string_view>
12+
#include <system_error>
13+
14+
extern "C" {
15+
#include <gg/ipc/mock.h>
16+
#include <gg/ipc/packet_sequences.h>
17+
#include <gg/test.h>
18+
#include <sys/types.h>
19+
#include <unistd.h>
20+
#include <unity.h>
21+
22+
GgError gg_process_wait(pid_t pid) noexcept;
23+
}
24+
25+
GG_TEST_DEFINE(cpp_create_local_deployment_okay) {
26+
GgBuffer expected_id = GG_STR("cpp-deploy-id-123");
27+
28+
GgObject merge_value = gg_obj_map(GG_MAP(gg_kv(
29+
GG_STR("proxy"),
30+
gg_obj_map(GG_MAP(
31+
gg_kv(GG_STR("url"), gg_obj_buf(GG_STR("http://127.0.0.1:3129")))
32+
))
33+
)));
34+
GgObject network_proxy
35+
= gg_obj_map(GG_MAP(gg_kv(GG_STR("networkProxy"), merge_value)));
36+
GgObject merge = gg_obj_map(GG_MAP(gg_kv(GG_STR("merge"), network_proxy)));
37+
GgMap component_to_config
38+
= GG_MAP(gg_kv(GG_STR("aws.greengrass.NucleusLite"), merge));
39+
40+
std::array<std::byte, 64> id_mem {};
41+
42+
pid_t pid = fork();
43+
TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork failed");
44+
45+
if (pid == 0) {
46+
auto &client = gg::ipc::Client::get();
47+
GG_TEST_ASSERT_OK(client.connect().value());
48+
49+
GgCreateLocalDeploymentArgs args = { 0 };
50+
args.component_to_configuration = component_to_config;
51+
52+
std::string_view deployment_id;
53+
GG_TEST_ASSERT_OK(client
54+
.create_local_deployment(
55+
args, std::span(id_mem), &deployment_id
56+
)
57+
.value());
58+
59+
TEST_ASSERT_EQUAL_STRING_LEN(
60+
"cpp-deploy-id-123", deployment_id.data(), deployment_id.size()
61+
);
62+
63+
TEST_PASS();
64+
}
65+
66+
GG_TEST_ASSERT_OK(gg_test_connect_request_disconnect_sequence(
67+
gg_test_create_local_deployment_accepted_sequence(
68+
1, gg_obj_map(component_to_config), expected_id
69+
),
70+
5
71+
));
72+
73+
GG_TEST_ASSERT_OK(gg_process_wait(pid));
74+
}
75+
76+
GG_TEST_DEFINE(cpp_create_local_deployment_no_output) {
77+
GgMap component_to_config = GG_MAP(gg_kv(
78+
GG_STR("aws.greengrass.NucleusLite"),
79+
gg_obj_map(GG_MAP(gg_kv(GG_STR("merge"), gg_obj_map(GG_MAP()))))
80+
));
81+
82+
pid_t pid = fork();
83+
TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork failed");
84+
85+
if (pid == 0) {
86+
auto &client = gg::ipc::Client::get();
87+
GG_TEST_ASSERT_OK(client.connect().value());
88+
89+
GgCreateLocalDeploymentArgs args = { 0 };
90+
args.component_to_configuration = component_to_config;
91+
92+
GG_TEST_ASSERT_OK(client.create_local_deployment(args).value());
93+
94+
TEST_PASS();
95+
}
96+
97+
GG_TEST_ASSERT_OK(gg_test_connect_request_disconnect_sequence(
98+
gg_test_create_local_deployment_accepted_sequence(
99+
1, gg_obj_map(component_to_config), GG_STR("any-id")
100+
),
101+
5
102+
));
103+
104+
GG_TEST_ASSERT_OK(gg_process_wait(pid));
105+
}

‎include/gg/ipc/client.h‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,41 @@ GgError ggipc_update_state(GgComponentState state);
116116
/// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-restartcomponent>
117117
GgError ggipc_restart_component(GgBuffer component_name);
118118

119+
/// Arguments for ggipc_create_local_deployment.
120+
/// All fields are optional; zero-initialize the struct to omit all fields
121+
/// (zero-initialized maps/lists are valid empty maps/lists).
122+
typedef struct {
123+
/// Map of component name → configuration merge map.
124+
GgMap component_to_configuration;
125+
/// Map of component name → version string to add as root components.
126+
GgMap root_component_versions_to_add;
127+
/// List of component name buffers to remove from root components.
128+
GgList root_components_to_remove;
129+
/// Path to a directory containing local recipe files.
130+
GgBuffer recipe_directory_path;
131+
/// Path to a directory containing local artifact files.
132+
GgBuffer artifacts_directory_path;
133+
/// Failure handling policy: "ROLLBACK" or "DO_NOTHING".
134+
GgBuffer failure_handling_policy;
135+
} GgCreateLocalDeploymentArgs;
136+
137+
/// Create a local deployment on the core device.
138+
/// Triggers a local deployment that can merge configuration into components,
139+
/// add/remove root components, and specify local
140+
/// recipe/artifact paths to overwrite the Greengrass recipe/artifact stores.
141+
///
142+
/// If `deployment_id` is not NULL, its `data` must point to a writable buffer
143+
/// of at least `deployment_id->len` bytes. On success, `deployment_id->len` is
144+
/// updated to the actual length of the returned deployment id string, which is
145+
/// written into the caller-provided buffer.
146+
///
147+
/// See:
148+
/// <https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-local-deployments-components.html#ipc-operation-createlocaldeployment>
149+
ACCESS(read_write, 2)
150+
GgError ggipc_create_local_deployment(
151+
const GgCreateLocalDeploymentArgs *args, GgBuffer *deployment_id
152+
) NONNULL(1);
153+
119154
/// Get component configuration value.
120155
/// Retrieves configuration for the specified key path.
121156
/// Pass empty list for complete config.

‎misc/dictionary.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ ffat
1010
fileb
1111
flto
1212
fstrict
13+
ggdeploymentd
1314
ggipc
1415
greengrassv2
1516
idents

‎mock/gg/ipc/packet_sequences.h‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,22 @@ GgipcPacketSequence gg_test_restart_component_error_sequence(
8484
int32_t stream_id, GgBuffer component_name
8585
);
8686

87+
GgipcPacketSequence gg_test_create_local_deployment_accepted_sequence(
88+
int32_t stream_id,
89+
GgObject component_to_configuration,
90+
GgBuffer deployment_id
91+
);
92+
93+
GgipcPacketSequence gg_test_create_local_deployment_error_sequence(
94+
int32_t stream_id, GgObject component_to_configuration
95+
);
96+
97+
GgipcPacketSequence gg_test_create_local_deployment_versions_accepted_sequence(
98+
int32_t stream_id,
99+
GgObject root_component_versions_to_add,
100+
GgBuffer deployment_id
101+
);
102+
87103
// Shadow sequences
88104

89105
GgipcPacketSequence gg_test_shadow_update_accepted_sequence(

‎mock/packets/component_packet_sequences.c‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,3 +114,101 @@ GgipcPacketSequence gg_test_restart_component_error_sequence(
114114
.len = 2
115115
};
116116
}
117+
118+
GgipcPacket gg_test_create_local_deployment_request_packet(
119+
int32_t stream_id, GgObject component_to_configuration
120+
) {
121+
static GgKV payload[1];
122+
payload[0]
123+
= gg_kv(GG_STR("componentToConfiguration"), component_to_configuration);
124+
size_t payload_len = sizeof(payload) / sizeof(payload[0]);
125+
126+
return (GgipcPacket) { .direction = CLIENT_TO_SERVER,
127+
.has_payload = true,
128+
.payload = gg_obj_map((GgMap) {
129+
.pairs = payload, .len = payload_len }),
130+
.headers = GG_IPC_REQUEST_HEADERS(
131+
stream_id, "aws.greengrass#CreateLocalDeployment"
132+
),
133+
.header_count = GG_IPC_REQUEST_HEADERS_COUNT };
134+
}
135+
136+
GgipcPacket gg_test_create_local_deployment_response_packet(
137+
int32_t stream_id, GgBuffer deployment_id
138+
) {
139+
static GgKV payload[1];
140+
payload[0] = gg_kv(GG_STR("deploymentId"), gg_obj_buf(deployment_id));
141+
size_t payload_len = sizeof(payload) / sizeof(payload[0]);
142+
143+
return (GgipcPacket) { .direction = SERVER_TO_CLIENT,
144+
.has_payload = true,
145+
.payload = gg_obj_map((GgMap) {
146+
.pairs = payload, .len = payload_len }),
147+
.headers = GG_IPC_ACCEPTED_HEADERS(
148+
stream_id, "aws.greengrass#CreateLocalDeployment"
149+
),
150+
.header_count = GG_IPC_ACCEPTED_HEADERS_COUNT };
151+
}
152+
153+
GgipcPacketSequence gg_test_create_local_deployment_accepted_sequence(
154+
int32_t stream_id,
155+
GgObject component_to_configuration,
156+
GgBuffer deployment_id
157+
) {
158+
return (GgipcPacketSequence) {
159+
.packets = { gg_test_create_local_deployment_request_packet(
160+
stream_id, component_to_configuration
161+
),
162+
gg_test_create_local_deployment_response_packet(
163+
stream_id, deployment_id
164+
) },
165+
.len = 2
166+
};
167+
}
168+
169+
GgipcPacketSequence gg_test_create_local_deployment_error_sequence(
170+
int32_t stream_id, GgObject component_to_configuration
171+
) {
172+
return (GgipcPacketSequence) {
173+
.packets = { gg_test_create_local_deployment_request_packet(
174+
stream_id, component_to_configuration
175+
),
176+
gg_test_ipc_permissions_error_packet(stream_id) },
177+
.len = 2
178+
};
179+
}
180+
181+
GgipcPacket gg_test_create_local_deployment_versions_request_packet(
182+
int32_t stream_id, GgObject root_component_versions_to_add
183+
) {
184+
static GgKV payload[1];
185+
payload[0] = gg_kv(
186+
GG_STR("rootComponentVersionsToAdd"), root_component_versions_to_add
187+
);
188+
size_t payload_len = sizeof(payload) / sizeof(payload[0]);
189+
190+
return (GgipcPacket) { .direction = CLIENT_TO_SERVER,
191+
.has_payload = true,
192+
.payload = gg_obj_map((GgMap) {
193+
.pairs = payload, .len = payload_len }),
194+
.headers = GG_IPC_REQUEST_HEADERS(
195+
stream_id, "aws.greengrass#CreateLocalDeployment"
196+
),
197+
.header_count = GG_IPC_REQUEST_HEADERS_COUNT };
198+
}
199+
200+
GgipcPacketSequence gg_test_create_local_deployment_versions_accepted_sequence(
201+
int32_t stream_id,
202+
GgObject root_component_versions_to_add,
203+
GgBuffer deployment_id
204+
) {
205+
return (GgipcPacketSequence) {
206+
.packets = { gg_test_create_local_deployment_versions_request_packet(
207+
stream_id, root_component_versions_to_add
208+
),
209+
gg_test_create_local_deployment_response_packet(
210+
stream_id, deployment_id
211+
) },
212+
.len = 2
213+
};
214+
}

‎mock/packets/packets.h‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,18 @@ GgipcPacket gg_test_restart_component_response_packet(
165165
int32_t stream_id, GgBuffer restart_status
166166
);
167167

168+
GgipcPacket gg_test_create_local_deployment_request_packet(
169+
int32_t stream_id, GgObject component_to_configuration
170+
);
171+
172+
GgipcPacket gg_test_create_local_deployment_response_packet(
173+
int32_t stream_id, GgBuffer deployment_id
174+
);
175+
176+
GgipcPacket gg_test_create_local_deployment_versions_request_packet(
177+
int32_t stream_id, GgObject root_component_versions_to_add
178+
);
179+
168180
// Shadow operations
169181

170182
GgipcPacket gg_test_shadow_update_request_packet(

0 commit comments

Comments
 (0)