Skip to main content

oasis_core_runtime/host/
bundle_manager.rs

1use std::collections::BTreeMap;
2
3use async_trait::async_trait;
4
5use crate::{common::crypto::hash::Hash, protocol::Protocol};
6
7use super::{host_rpc_call, Error};
8
9/// Name of the local RPC endpoint for the bundle manager.
10pub const LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER: &str = "bundle-manager";
11
12/// Name of the BundleTemporaryWrite method.
13pub const METHOD_BUNDLE_TEMPORARY_WRITE: &str = "BundleTemporaryWrite";
14/// Name of the BundleTemporaryDelete method.
15pub const METHOD_BUNDLE_TEMPORARY_DELETE: &str = "BundleTemporaryDelete";
16/// Name of the BundleAdd method.
17pub const METHOD_BUNDLE_ADD: &str = "BundleAdd";
18/// Name of the BundleRemove method.
19pub const METHOD_BUNDLE_REMOVE: &str = "BundleRemove";
20/// Name of the BundleList method.
21pub const METHOD_BUNDLE_LIST: &str = "BundleList";
22
23/// Name of the special label that identifies the instance.
24pub const LABEL_INSTANCE_ID: &str = "net.oasis.instance_id";
25
26/// Bundle manager interface.
27#[allow(clippy::double_must_use)]
28#[async_trait]
29pub trait BundleManager: Send + Sync {
30    /// Request to host to write a chunk of the bundle to a temporary file.
31    ///
32    /// The `PermissionBundleAdd` permission is required to call this method.
33    async fn bundle_temporary_write(
34        &self,
35        args: BundleTemporaryWriteRequest,
36    ) -> Result<BundleTemporaryWriteResponse, Error>;
37
38    /// Request to host to delete a temporary bundle file.
39    ///
40    /// The `PermissionBundleAdd` permission is required to call this method.
41    async fn bundle_temporary_delete(
42        &self,
43        args: BundleTemporaryDeleteRequest,
44    ) -> Result<BundleTemporaryDeleteResponse, Error>;
45
46    /// Request to host to add a specific bundle to the host.
47    ///
48    /// The `PermissionBundleAdd` permission is required to call this method.
49    async fn bundle_add(&self, args: BundleAddRequest) -> Result<BundleAddResponse, Error>;
50
51    /// Request to host to remove a specific component. Only components added by this component
52    /// can be removed.
53    ///
54    /// The `PermissionBundleRemove` permission is required to call this method.
55    async fn bundle_remove(&self, args: BundleRemoveRequest)
56        -> Result<BundleRemoveResponse, Error>;
57
58    /// Request to host to list all bundles.
59    ///
60    /// The `PermissionBundleAdd` permission is required to call this method.
61    async fn bundle_list(&self, args: BundleListRequest) -> Result<BundleListResponse, Error>;
62}
63
64#[allow(clippy::double_must_use)]
65#[async_trait]
66impl BundleManager for Protocol {
67    async fn bundle_temporary_write(
68        &self,
69        args: BundleTemporaryWriteRequest,
70    ) -> Result<BundleTemporaryWriteResponse, Error> {
71        host_rpc_call(
72            self,
73            LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER,
74            METHOD_BUNDLE_TEMPORARY_WRITE,
75            args,
76        )
77        .await
78    }
79
80    async fn bundle_temporary_delete(
81        &self,
82        args: BundleTemporaryDeleteRequest,
83    ) -> Result<BundleTemporaryDeleteResponse, Error> {
84        host_rpc_call(
85            self,
86            LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER,
87            METHOD_BUNDLE_TEMPORARY_DELETE,
88            args,
89        )
90        .await
91    }
92
93    async fn bundle_add(&self, args: BundleAddRequest) -> Result<BundleAddResponse, Error> {
94        host_rpc_call(
95            self,
96            LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER,
97            METHOD_BUNDLE_ADD,
98            args,
99        )
100        .await
101    }
102
103    async fn bundle_remove(
104        &self,
105        args: BundleRemoveRequest,
106    ) -> Result<BundleRemoveResponse, Error> {
107        host_rpc_call(
108            self,
109            LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER,
110            METHOD_BUNDLE_REMOVE,
111            args,
112        )
113        .await
114    }
115
116    async fn bundle_list(&self, args: BundleListRequest) -> Result<BundleListResponse, Error> {
117        host_rpc_call(
118            self,
119            LOCAL_RPC_ENDPOINT_BUNDLE_MANAGER,
120            METHOD_BUNDLE_LIST,
121            args,
122        )
123        .await
124    }
125}
126
127/// Request to host to write a chunk of the bundle to a temporary file.
128///
129/// The `PermissionBundleAdd` permission is required to call this method.
130#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
131pub struct BundleTemporaryWriteRequest {
132    /// Temporary file name to use on the host while writing the bundle.
133    pub temporary_name: String,
134    /// Optional flag which specifies that the temporary file should be recreated. If the file
135    /// exists and this flag is set to true, it will be truncated. If the flag is set to false, any
136    /// content will be appended to the existing file.
137    pub create: bool,
138    /// Data that should be appended to the temporary file.
139    pub data: Vec<u8>,
140}
141
142/// Response form the BundleTemporaryWrite method.
143#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
144pub struct BundleTemporaryWriteResponse {}
145
146/// Request to host to delete a temporary bundle file.
147///
148/// The `PermissionBundleAdd` permission is required to call this method.
149#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
150pub struct BundleTemporaryDeleteRequest {
151    /// Temporary file name to delete on the host.
152    pub temporary_name: String,
153}
154
155/// Response from the BundleTemporaryDelete method.
156#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
157pub struct BundleTemporaryDeleteResponse {}
158
159/// Request to host to add a specific bundle to the host.
160///
161/// The `PermissionBundleAdd` permission is required to call this method.
162#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
163pub struct BundleAddRequest {
164    /// Temporary file name to read the bundle from. The file must have previously been created by
165    /// using `BundleTemporaryWrite`.
166    ///
167    /// The file must be a valid bundle.
168    pub temporary_name: String,
169    /// Expected hash of the manifest contained inside the bundle.
170    pub manifest_hash: Hash,
171    /// Labels to tag the bundle with.
172    ///
173    /// Note that the host will assign a random component identifier to these components, so one
174    /// should use labels to later be able to find them.
175    ///
176    /// Use the special `LABEL_INSTANCE_ID` label to specify a deterministic instance ID.
177    pub labels: BTreeMap<String, String>,
178    /// Volumes to attach to the bundle.
179    pub volumes: BTreeMap<String, String>,
180}
181
182/// Response form the BundleAdd method.
183#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
184pub struct BundleAddResponse {}
185
186/// Request to host to remove a specific component. Only components added by this component can be
187/// removed.
188///
189/// The `PermissionBundleRemove` permission is required to call this method.
190#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
191pub struct BundleRemoveRequest {
192    /// Labels to filter the components by.
193    pub labels: BTreeMap<String, String>,
194}
195
196/// Response form the BundleRemove method.
197#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
198pub struct BundleRemoveResponse {}
199
200/// Request to host to list all bundles.
201///
202/// The `PermissionBundleAdd` permission is required to call this method.
203#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
204pub struct BundleListRequest {
205    /// Labels to filter the components by.
206    pub labels: BTreeMap<String, String>,
207}
208
209/// Response from host to list all bundles.
210#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
211pub struct BundleListResponse {
212    /// The resulting bundles.
213    #[cbor(optional)]
214    pub bundles: Vec<BundleInfo>,
215}
216
217/// Bundle information.
218#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
219pub struct BundleInfo {
220    /// Hash of the manifest.
221    pub manifest_hash: Hash,
222    /// List of all components in this bundle.
223    pub components: Vec<ComponentInfo>,
224    /// Labels assigned to this bundle.
225    pub labels: BTreeMap<String, String>,
226}
227
228/// Component information.
229#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
230pub struct ComponentInfo {
231    /// Component name.
232    pub name: String,
233}