|
| 1 | +# Rust client |
| 2 | + |
| 3 | +The Rust client library for Windmill provides a convenient way to interact with the Windmill platform's API from within your Rust applications. By authenticating with the `WM_TOKEN` reserved variable or custom tokens, you can utilize the Rust client to access various functionalities offered by Windmill. |
| 4 | + |
| 5 | +<div className="inline-flex gap-2"> |
| 6 | + <a href="https://crates.io/crates/wmill"><img src="https://img.shields.io/crates/v/wmill" alt="crates.io" /></a> |
| 7 | + <a href="https://docs.rs/wmill"><img src="https://img.shields.io/docsrs/wmill" alt="docs.rs" /></a> |
| 8 | +</div> |
| 9 | + |
| 10 | +## Installation |
| 11 | + |
| 12 | +To use the Rust client library, you need to add the `wmill` crate to your `Cargo.toml` dependencies: |
| 13 | + |
| 14 | +```toml |
| 15 | +[dependencies] |
| 16 | +wmill = "^1.0" |
| 17 | +``` |
| 18 | + |
| 19 | +Or using cargo: |
| 20 | + |
| 21 | +```bash |
| 22 | +cargo add wmill |
| 23 | +``` |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | + |
| 28 | +## Usage |
| 29 | + |
| 30 | +### Initialize Client |
| 31 | + |
| 32 | +```rust |
| 33 | +use wmill::Windmill; |
| 34 | + |
| 35 | +#[tokio::main] |
| 36 | +async fn main() -> Result<(), Box<dyn std::error::Error>> { |
| 37 | + // Read config from env vars |
| 38 | + let wm = Windmill::default()?; |
| 39 | + |
| 40 | + // Or override specific values |
| 41 | + let wm = Windmill::new( |
| 42 | + Some("custom_token".to_string()), |
| 43 | + Some("my_workspace".to_string()), |
| 44 | + Some("http://localhost:8000".to_string()) |
| 45 | + )?; |
| 46 | + |
| 47 | + Ok(()) |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +### Variables |
| 52 | + |
| 53 | +```rust |
| 54 | +// Get variable (auto-parsed) |
| 55 | +let db_config: serde_json::Value = wm.get_variable("u/admin/db_config").await?; |
| 56 | + |
| 57 | +// Get raw variable |
| 58 | +let raw_text = wm.get_variable_raw("u/user/text_note").await?; |
| 59 | + |
| 60 | +// Set variable |
| 61 | +wm.set_variable("new_value".to_string(), "u/user/my_var", false).await?; |
| 62 | +``` |
| 63 | + |
| 64 | +### Resources |
| 65 | + |
| 66 | +```rust |
| 67 | +// Get resource (typed) |
| 68 | +#[derive(serde::Deserialize)] |
| 69 | +struct DbConfig { host: String, port: u16 } |
| 70 | + |
| 71 | +let config: DbConfig = wm.get_resource("u/admin/db").await?; |
| 72 | + |
| 73 | +// Get raw resource |
| 74 | +let raw_json = wm.get_resource_any("u/admin/db").await?; |
| 75 | + |
| 76 | +// Set resource |
| 77 | +wm.set_resource( |
| 78 | + Some(serde_json::json!({"host": "localhost", "port": 5432})), |
| 79 | + "u/admin/db", |
| 80 | + "postgresql" |
| 81 | +).await?; |
| 82 | +``` |
| 83 | + |
| 84 | +### Scripts |
| 85 | + |
| 86 | +```rust |
| 87 | +// Run script async |
| 88 | +let job_id = wm.run_script_async( |
| 89 | + "u/user/my_script", |
| 90 | + false, |
| 91 | + serde_json::json!({"param": "value"}), |
| 92 | + Some(10) // Schedule in 10 seconds |
| 93 | +).await?; |
| 94 | + |
| 95 | +// Run script sync |
| 96 | +let result = wm.run_script_sync( |
| 97 | + "u/user/my_script", |
| 98 | + false, |
| 99 | + serde_json::json!({"param": "value"}), |
| 100 | + Some(10), |
| 101 | + Some(30), // 30s timeout |
| 102 | + true, // Verbose |
| 103 | + true // Assert result not None |
| 104 | +).await?; |
| 105 | +``` |
| 106 | + |
| 107 | +### Jobs |
| 108 | + |
| 109 | +```rust |
| 110 | +// Wait for job completion |
| 111 | +let result = wm.wait_job(&job_id, Some(60), true, true).await?; |
| 112 | + |
| 113 | +// Get job status |
| 114 | +let status = wm.get_job_status(&job_id).await?; // Running/Waiting/Completed |
| 115 | + |
| 116 | +// Get result directly |
| 117 | +let result = wm.get_result(&job_id).await?; |
| 118 | +``` |
| 119 | + |
| 120 | +### State Management |
| 121 | + |
| 122 | +```rust |
| 123 | +// Get typed state |
| 124 | +#[derive(serde::Deserialize)] |
| 125 | +struct ScriptState { counter: i32 } |
| 126 | + |
| 127 | +let state: ScriptState = wm.get_state().await?; |
| 128 | + |
| 129 | +// Get raw state |
| 130 | +let raw_state = wm.get_state_any().await?; |
| 131 | + |
| 132 | +// Update state |
| 133 | +wm.set_state(Some(serde_json::json!({"counter": 42}))).await?; |
| 134 | +``` |
| 135 | + |
| 136 | +### Progress Tracking |
| 137 | + |
| 138 | +```rust |
| 139 | +// Set job progress |
| 140 | +wm.set_progress(75, None).await?; // Uses current job ID from env |
| 141 | + |
| 142 | +// Get job progress |
| 143 | +let progress = wm.get_progress(Some(job_id.to_string())).await?; |
| 144 | +``` |
| 145 | + |
| 146 | +### Custom API Calls |
| 147 | + |
| 148 | +The SDK provides direct access to underlying API endpoints through the ```call_api``` method, which works in both async and sync contexts: |
| 149 | + |
| 150 | +```rust |
| 151 | +// Async usage |
| 152 | +#[tokio::main] |
| 153 | +async fn main() -> Result<(), Box<dyn std::error::Error>> { |
| 154 | + let wm = Windmill::default()?; |
| 155 | + |
| 156 | + // Make direct API call to get user |
| 157 | + let user = wm.call_api(wmill::apis::admin_api::get_user( |
| 158 | + &wm.client_config, |
| 159 | + &wm.workspace, |
| 160 | + "Alice" |
| 161 | + )).await; |
| 162 | + |
| 163 | + println!("User details: {:?}", user); |
| 164 | + Ok(()) |
| 165 | +} |
| 166 | + |
| 167 | +// Sync usage |
| 168 | +fn main() { |
| 169 | + let wm = Windmill::default().unwrap(); |
| 170 | + |
| 171 | + // Make direct API call to get user |
| 172 | + let user = wm.call_api(wmill::apis::admin_api::get_user( |
| 173 | + &wm.client_config, |
| 174 | + &wm.workspace, |
| 175 | + "Bob" |
| 176 | + )); |
| 177 | + |
| 178 | + println!("User details: {:?}", user); |
| 179 | +} |
| 180 | +``` |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments