volcengine_rust_sdk/volcengine/request/operation.rs
1/*
2 * @Author: Jerry.Yang
3 * @Date: 2024-10-17 16:33:22
4 * @LastEditors: Jerry.Yang
5 * @LastEditTime: 2025-02-05 11:07:30
6 * @Description: Operation
7 *
8 * This code defines an `Operation` struct that represents an HTTP operation
9 * (e.g., API requests). It uses a builder pattern for constructing the operation
10 * with various attributes such as `name`, `http_method`, and `http_path`.
11 * The code also defines related enums and helper methods.
12 */
13use crate::volcengine::error::error;
14use crate::volcengine::request::operation_config;
15
16/// Represents an HTTP operation with a name, HTTP method, and HTTP path.
17#[derive(Debug, Clone)]
18pub struct Operation {
19 // The name of the operation (e.g., GetUser, CreateUser).
20 pub name: operation_config::operation_name::OperationName,
21 // The HTTP method used for the operation (e.g., GET, POST).
22 pub http_method: operation_config::operation_http_method::OperationHttpMethod,
23 // The HTTP path for the operation (e.g., "/user").
24 pub http_path: operation_config::operation_http_path::OperationHttpPath,
25}
26
27impl Operation {
28 /// Provides a builder to construct an `Operation` instance step by step.
29 ///
30 /// This method returns a new `OperationBuilder` object. The builder pattern allows for
31 /// gradual construction of the `Operation` object, with flexibility to set each field
32 /// individually and validate them before finalizing the construction.
33 ///
34 /// # Returns
35 /// A new `OperationBuilder` to build the `Operation` object.
36 pub fn builder() -> OperationBuilder {
37 // Initialize an empty builder with no fields set.
38 OperationBuilder {
39 name: None,
40 http_method: None,
41 http_path: None,
42 }
43 }
44}
45
46/// Builder struct used to gradually build an `Operation` instance.
47pub struct OperationBuilder {
48 // Optional name of the operation (e.g., "GetUser").
49 pub name: Option<operation_config::operation_name::OperationName>,
50 // Optional HTTP method for the operation (e.g., GET, POST).
51 pub http_method: Option<operation_config::operation_http_method::OperationHttpMethod>,
52 // Optional HTTP path for the operation (e.g., "/user").
53 pub http_path: Option<operation_config::operation_http_path::OperationHttpPath>,
54}
55
56impl OperationBuilder {
57 /// Sets the operation name in the builder.
58 ///
59 /// This method allows you to set the `name` field of the `Operation` object that will
60 /// be constructed. The operation name typically corresponds to the action or API endpoint
61 /// (e.g., "GetUser", "CreateUser").
62 ///
63 /// # Arguments
64 /// * `operation_name` - The name of the operation (e.g., "GetUser").
65 ///
66 /// # Returns
67 /// The builder with the updated operation name.
68 pub fn with_operation_name(
69 mut self,
70 operation_name: operation_config::operation_name::OperationName,
71 ) -> Self {
72 self.name = Some(operation_name);
73 self
74 }
75
76 /// Sets the HTTP method in the builder.
77 ///
78 /// This method allows you to set the `http_method` field of the `Operation` object that will
79 /// be constructed. The HTTP method determines whether the request will use GET, POST, PUT, etc.
80 ///
81 /// # Arguments
82 /// * `operation_http_method` - The HTTP method for the operation (e.g., GET, POST).
83 ///
84 /// # Returns
85 /// The builder with the updated HTTP method.
86 pub fn with_operation_http_method(
87 mut self,
88 operation_http_method: operation_config::operation_http_method::OperationHttpMethod,
89 ) -> Self {
90 self.http_method = Some(operation_http_method);
91 self
92 }
93
94 /// Sets the HTTP path in the builder.
95 ///
96 /// This method allows you to set the `http_path` field of the `Operation` object that will
97 /// be constructed. The HTTP path defines the specific API endpoint or route for the operation
98 /// (e.g., "/user", "/product").
99 ///
100 /// # Arguments
101 /// * `operation_http_path` - The HTTP path for the operation (e.g., "/user").
102 ///
103 /// # Returns
104 /// The builder with the updated HTTP path.
105 pub fn with_operation_http_path(
106 mut self,
107 operation_http_path: operation_config::operation_http_path::OperationHttpPath,
108 ) -> Self {
109 self.http_path = Some(operation_http_path);
110 self
111 }
112
113 /// Finalizes the builder and creates an `Operation` instance.
114 ///
115 /// This method validates the required fields and constructs the `Operation` object.
116 /// If any required fields are missing, it returns an error. Otherwise, it returns the
117 /// fully constructed `Operation`.
118 ///
119 /// # Returns
120 /// * `Ok(Operation)` - A fully constructed `Operation` if all fields are provided.
121 /// * `Err(Error)` - An error if any required fields are missing.
122 pub fn build(self) -> Result<Operation, error::Error> {
123 // Validate that the operation name is provided.
124 if self.name.is_none() {
125 return Err(error::Error::ErrUtilRequestBuildOperationNo(
126 "operation_name".to_string(),
127 ));
128 }
129
130 // Validate that the HTTP method is provided.
131 if self.http_method.is_none() {
132 return Err(error::Error::ErrUtilRequestBuildOperationNo(
133 "operation_http_method".to_string(),
134 ));
135 }
136
137 // The HTTP path is optional and defaults to a default value if not provided, so it's not strictly validated.
138 // If not provided, the operation will still be built with a default path.
139 //
140 // Validate HTTP path if needed:
141 // if self.http_path.is_none() {
142 // return Err(error::Error::ErrUtilRequestBuildOperationNo(
143 // "operation_http_path".to_string(),
144 // ));
145 // }
146
147 // Return a new Operation instance after validating all required fields.
148 Ok(Operation {
149 name: self.name.unwrap(),
150 http_method: self.http_method.unwrap(),
151 // Use the provided http_path, or default to an empty path if not specified.
152 http_path: self.http_path.unwrap_or_default(),
153 })
154 }
155}