blueprint_tangle_extra/metadata/
job_definition.rs

1//! Job definition traits and implementations for Tangle jobs.
2//!
3//! This module provides traits and implementations for converting Rust functions into Tangle job
4//! definitions that can be registered with a Tangle Services pallet. The main traits are:
5//!
6//! - [`IntoJobMetadata`]: Converts a type into [`JobMetadata`]
7//! - [`IntoJobDefinition`]: Converts a [`Job`] function into a complete [`JobDefinition`]
8//! - [`IntoTangleFieldTypes`]: Defines how a type maps to a Tangle [`FieldType`]
9//!
10//! # Examples
11//!
12//! ```
13//! use blueprint_core::extract::Context;
14//! use blueprint_tangle_extra::extract::TangleArg;
15//! use blueprint_tangle_extra::extract::TangleResult;
16//! use blueprint_tangle_extra::metadata::IntoJobDefinition;
17//!
18//! // Define a simple squaring job
19//! async fn square_job(
20//!     Context(_): Context<u64>,
21//!     TangleArg(x): TangleArg<u64>,
22//! ) -> TangleResult<u64> {
23//!     TangleResult(x * x)
24//! }
25//!
26//! // Convert the function into a job definition
27//! let job_definition = square_job.into_job_definition();
28//! ```
29//!
30//! [`Job`]: blueprint_core::Job
31
32use crate::serde::{BoundedVec, new_bounded_string};
33use tangle_subxt::tangle_testnet_runtime::api::runtime_types::tangle_primitives::services::field::FieldType;
34use tangle_subxt::tangle_testnet_runtime::api::runtime_types::tangle_primitives::services::jobs::{
35    JobDefinition, JobMetadata,
36};
37
38/// Trait for types that can be converted into job metadata.
39///
40/// This trait is implemented for all types and uses the type name as the job name.
41pub trait IntoJobMetadata {
42    /// Converts the type into job metadata.
43    ///
44    /// # Returns
45    ///
46    /// A [`JobMetadata`] instance with the name set to the type name.
47    fn into_job_metadata(self) -> JobMetadata;
48}
49
50impl<T> IntoJobMetadata for T {
51    fn into_job_metadata(self) -> JobMetadata {
52        JobMetadata {
53            name: new_bounded_string(core::any::type_name::<T>().to_string()),
54            description: None,
55        }
56    }
57}
58
59/// Trait for types that can be converted into a job definition.
60///
61/// This trait is implemented for functions that can be executed as Tangle jobs.
62pub trait IntoJobDefinition<T> {
63    /// Converts the implementor into a job definition.
64    ///
65    /// # Returns
66    ///
67    /// A [`JobDefinition`] instance with metadata, parameters, and result types.
68    fn into_job_definition(self) -> JobDefinition;
69}
70
71/// Trait for types that can be converted into Tangle field types.
72///
73/// This trait defines how a Rust type maps to Tangle field types.
74pub trait IntoTangleFieldTypes {
75    /// Returns a vector of [`FieldType`] values that represent the type.
76    ///
77    /// # Returns
78    ///
79    /// A vector of [`FieldType`] values.
80    fn into_tangle_fields() -> Vec<FieldType>;
81}
82
83impl IntoTangleFieldTypes for blueprint_core::job::result::Void {
84    fn into_tangle_fields() -> Vec<FieldType> {
85        Vec::from([FieldType::Void])
86    }
87}
88
89/// Implementation for functions with no arguments.
90impl<F, Fut, Res> IntoJobDefinition<((),)> for F
91where
92    F: FnOnce() -> Fut + Clone + Send + Sync + 'static,
93    Fut: Future<Output = Res> + Send,
94    Res: IntoTangleFieldTypes,
95{
96    fn into_job_definition(self) -> JobDefinition {
97        JobDefinition {
98            metadata: self.into_job_metadata(),
99            params: BoundedVec(Vec::new()),
100            result: BoundedVec(Res::into_tangle_fields()),
101        }
102    }
103}
104
105/// Macro to implement [`IntoJobDefinition`] for functions with arguments.
106///
107/// This macro generates implementations for functions with different numbers of arguments.
108macro_rules! impl_into_job_definition {
109    (
110        [$($ty:ident),*], $last:ident
111    ) => {
112        impl<F, Fut, Res, $($ty,)* $last> IntoJobDefinition<((), $($ty,)* $last,)> for F
113        where
114            F: FnOnce($($ty,)* $last,) -> Fut + Clone + Send + Sync + 'static,
115            Fut: Future<Output = Res> + Send,
116            $last: IntoTangleFieldTypes,
117            Res: IntoTangleFieldTypes,
118        {
119            fn into_job_definition(self) -> JobDefinition {
120                JobDefinition {
121                    metadata: self.into_job_metadata(),
122                    params: BoundedVec($last::into_tangle_fields()),
123                    result: BoundedVec(Res::into_tangle_fields()),
124                }
125            }
126        }
127    };
128}
129
130// Use the all_the_tuples macro from blueprint_core to generate implementations
131// for functions with different numbers of arguments.
132blueprint_core::all_the_tuples!(impl_into_job_definition);
133
134#[cfg(test)]
135#[allow(clippy::type_complexity)]
136mod tests {
137    use blueprint_core::extract::Context;
138
139    use super::*;
140    use crate::extract::{
141        TangleArg, TangleArgs2, TangleArgs3, TangleArgs4, TangleArgs5, TangleArgs6, TangleArgs7,
142        TangleArgs8, TangleArgs9, TangleArgs10, TangleArgs11, TangleArgs12, TangleArgs13,
143        TangleArgs14, TangleArgs15, TangleArgs16, TangleResult,
144    };
145
146    macro_rules! count {
147        ($val:ident, $($rest:tt)*) => {
148            1 + count!($($rest)*)
149        };
150        ($val:ident) => {
151            1
152        };
153        () => {
154            0
155        }
156    }
157
158    async fn empty() -> TangleResult<u64> {
159        TangleResult(0)
160    }
161
162    #[test]
163    fn empty_test() {
164        let empty = empty.into_job_definition();
165        assert_eq!(
166            empty.metadata.name.0.0,
167            b"blueprint_tangle_extra::metadata::job_definition::tests::empty",
168            "expected empty, got {}",
169            std::str::from_utf8(&empty.metadata.name.0.0).unwrap()
170        );
171        assert!(empty.params.0.is_empty());
172        assert_eq!(empty.result.0[0], FieldType::Uint64);
173    }
174
175    #[derive(Debug, Default, Clone, Copy)]
176    struct MyContext {
177        foo: u64,
178    }
179
180    #[derive(Debug)]
181    struct MyError;
182
183    impl std::fmt::Display for MyError {
184        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
185            write!(f, "MyError")
186        }
187    }
188
189    impl std::error::Error for MyError {}
190
191    macro_rules! definition_tests {
192        ($($func:ident($args_ty:ident($($args:ident),*): $ty:ty));* $(;)?) => {
193            $(
194                #[allow(unused_variables)]
195                async fn $func($args_ty($($args),*): $ty) -> TangleResult<u64> {
196                    todo!()
197                }
198
199                paste::paste! {
200                    #[allow(unused_variables)]
201                    #[allow(clippy::type_complexity)]
202                    async fn [<$func _with_context>](Context(ctx): Context<MyContext>, $args_ty($($args),*): $ty) -> TangleResult<u64> {
203                        eprintln!("ctx: {:?}", ctx.foo);
204                        todo!()
205                    }
206
207                    #[allow(unused_variables)]
208                    #[allow(clippy::type_complexity)]
209                    async fn [<$func _with_context_ret_res>](Context(ctx): Context<MyContext>, $args_ty($($args),*): $ty) -> Result<TangleResult<u64>, MyError> {
210                        eprintln!("ctx: {:?}", ctx.foo);
211                        todo!()
212                    }
213
214
215                    #[allow(unused_variables)]
216                    #[allow(clippy::type_complexity)]
217                    async fn [<$func _with_context_ret_opt>](Context(ctx): Context<MyContext>, $args_ty($($args),*): $ty) -> Option<TangleResult<u64>> {
218                        eprintln!("ctx: {:?}", ctx.foo);
219                        todo!()
220                    }
221
222                    #[test]
223                    fn [<$func _test>]() {
224                        let def = $func.into_job_definition();
225                        assert_eq!(
226                            def.metadata.name.0.0,
227                            format!("blueprint_tangle_extra::metadata::job_definition::tests::{}", stringify!($func)).as_bytes(),
228                        );
229                        assert_eq!(def.params.0.len(), count!($($args),*));
230                        assert_eq!(def.result.0.len(), 1);
231                        assert!(def.params.0.iter().all(|ty| ty.clone() == FieldType::Uint64));
232                        assert_eq!(def.result.0[0], FieldType::Uint64);
233
234                        let def2 = [<$func _with_context>].into_job_definition();
235                        assert_eq!(
236                            def2.metadata.name.0.0,
237                            format!("blueprint_tangle_extra::metadata::job_definition::tests::{}", stringify!([<$func _with_context>])).as_bytes(),
238                        );
239                        assert_eq!(def2.params.0.len(), count!($($args),*));
240                        assert_eq!(def2.result.0.len(), 1);
241                        assert!(def2.params.0.iter().all(|ty| ty.clone() == FieldType::Uint64));
242                        assert_eq!(def2.result.0[0], FieldType::Uint64);
243
244
245                        let def3 = [<$func _with_context_ret_res>].into_job_definition();
246                        assert_eq!(
247                            def3.metadata.name.0.0,
248                            format!("blueprint_tangle_extra::metadata::job_definition::tests::{}", stringify!([<$func _with_context_ret_res>])).as_bytes(),
249                        );
250                        assert_eq!(def3.params.0.len(), count!($($args),*));
251                        assert_eq!(def3.result.0.len(), 1);
252                        assert!(def3.params.0.iter().all(|ty| ty.clone() == FieldType::Uint64));
253                        assert_eq!(def3.result.0[0], FieldType::Uint64);
254
255                        let def4 = [<$func _with_context_ret_opt>].into_job_definition();
256                        assert_eq!(
257                            def4.metadata.name.0.0,
258                            format!("blueprint_tangle_extra::metadata::job_definition::tests::{}", stringify!([<$func _with_context_ret_opt>])).as_bytes(),
259                        );
260                        assert_eq!(def4.params.0.len(), count!($($args),*));
261                        assert_eq!(def4.result.0.len(), 1);
262                        assert!(def4.params.0.iter().all(|ty| ty.clone() == FieldType::Uint64));
263                        assert_eq!(def4.result.0[0], FieldType::Uint64);
264
265                    }
266                }
267            )*
268        }
269    }
270
271    definition_tests!(
272        xsquare(TangleArg(x): TangleArg<u64>);
273        xsquare2(TangleArgs2(x, y): TangleArgs2<u64, u64>);
274        xsquare3(TangleArgs3(x, y, z): TangleArgs3<u64, u64, u64>);
275        xsquare4(TangleArgs4(x, y, z, w): TangleArgs4<u64, u64, u64, u64>);
276        xsquare5(TangleArgs5(x, y, z, w, v): TangleArgs5<u64, u64, u64, u64, u64>);
277        xsquare6(TangleArgs6(x, y, z, w, v, u): TangleArgs6<u64, u64, u64, u64, u64, u64>);
278        xsquare7(TangleArgs7(x, y, z, w, v, u, t): TangleArgs7<u64, u64, u64, u64, u64, u64, u64>);
279        xsquare8(TangleArgs8(x, y, z, w, v, u, t, s): TangleArgs8<u64, u64, u64, u64, u64, u64, u64, u64>);
280        xsquare9(TangleArgs9(x, y, z, w, v, u, t, s, r): TangleArgs9<u64, u64, u64, u64, u64, u64, u64, u64, u64>);
281        xsquare10(TangleArgs10(x, y, z, w, v, u, t, s, r, q): TangleArgs10<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
282        xsquare11(TangleArgs11(x, y, z, w, v, u, t, s, r, q, p): TangleArgs11<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
283        xsquare12(TangleArgs12(x, y, z, w, v, u, t, s, r, q, p, o): TangleArgs12<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
284        xsquare13(TangleArgs13(x, y, z, w, v, u, t, s, r, q, p, o, n): TangleArgs13<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
285        xsquare14(TangleArgs14(x, y, z, w, v, u, t, s, r, q, p, o, n, m): TangleArgs14<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
286        xsquare15(TangleArgs15(x, y, z, w, v, u, t, s, r, q, p, o, n, m, l): TangleArgs15<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
287        xsquare16(TangleArgs16(x, y, z, w, v, u, t, s, r, q, p, o, n, m, l, k): TangleArgs16<u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64, u64>);
288    );
289}
blueprint_tangle_extra/metadata/job_definition.rs

blueprint_tangle_extra/metadata/
job_definition.rs
