mirror of
https://github.com/windmill-labs/windmill.git
synced 2026-11-17 00:20:51 +00:00
* feat: run a workspace handler when a secret variable expires Secret variables gain an optional `value_expires_at`, and a workspace can point at a script or flow to run once that date passes, so a rotation is driven by the platform instead of tracked out of band. The secret never leaves the database. The sweep selects the path, description and expiry and nothing else, so the handler is given a reference to rotate rather than a value to handle. Job results are stored in cleartext and shown in Runs, which is what makes that a boundary rather than a preference; a test asserts the job's args never contain the value. Each row is claimed by writing `expiration_dispatched_for` in the same transaction as the push, so a failed push un-claims it and a lost race claims nothing. Moving the date re-arms the row; re-saving the same date does not. A pass takes at most 100 rows under a transaction-scoped advisory lock, and orders so that one broken workspace cannot starve the rest. Dispatch runs as `g/variable_expiration_handler`, exempt from the CE group limit and from non-premium exec metering the way the error and schedule handlers already are. A handler that keeps failing backs off and raises a critical alert instead of retrying every pass, and the back-off ends when the handler is repointed. The expiry travels with the variable through workspace clone, tarball export and workspace comparison. The dispatch marker deliberately does not, so a fork re-arms on its own copy. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(frontend): expose variable value expiration in the UI The variable drawer takes an optional expiry on a secret value, and the variables list badges it, turning red once the date has passed. A workspace settings tab picks the handler, its extra args, and whether variables under `u/` are skipped. That mute flag is stored inside the handler setting, so the toggle stays disabled until a handler is picked: saving it on its own would clear the setting it lives in and still report success. The expiry is carried as a tri-state through the draft deploy and copilot paths — absent leaves the remote value alone, an explicit null clears it — so deploying a draft cannot silently drop a date someone set elsewhere. The settings tab names the one case where the configured identity does not apply: a handler script carrying `on_behalf_of` runs as that user rather than as `g/variable_expiration_handler`, which matters because the same tab asks the admin to grant that group write access to the variables it rotates. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cli): sync variable expiry and the workspace expiration handler `wmill sync` carries `value_expires_at` on variables in both directions, and pushes the workspace handler alongside the error and success handlers in the grouped settings format. Dropping the key from a variable's yaml clears the remote expiry, so the file stays canonical rather than accumulating fields that can only ever be added. The handler follows the same rule, with the caveat recorded where the type is declared: an omitted handler only reaches the clear when some other setting differs, because the push short-circuits on a comparison that walks the local object's keys and so never sees a missing one. That gate is shared with the two existing handlers and is left as it is here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(frontend): open the variable expiration handler template in a new tab The "Create a handler" button hands its script template to /scripts/add through the URL hash, which `load` reads from `window.location`. A client-side navigation leaves the previous page's hash in place, so the payload was dropped and the editor opened on the default template at a `u/` path. `target="_blank"` forces a full page load, matching the success handler's "Create from template" button. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(frontend): make the variable expiry field state its own status The expiry field rendered a DateTimeInput whose time defaults to 12:00 when it holds no value, so a variable with no expiry looked like one already configured, and "cleared" looked identical to "never set". Setting an expiry is optional, so the field has to say which it is. Rebuild it on the shape ScriptAdvancedSettings already uses for Timeout, Cache and Concurrency limits: a toggle whose checked state is the stored value being present, seeding a date on enable rather than revealing an empty picker, with the input under its own label. Drop `clearable` with it, so the toggle is the single way to mean "no expiry" instead of competing with an X. Stop the surrounding copy promising a run that may not happen. A handler is only dispatched if the workspace has one configured and does not skip u/ paths, so the list tooltip now states the date alone, and the form hedges both conditions, naming the u/ mute only on personal paths where it can apply. Also anchor the mute toggle's tooltip: Popover's trigger is a span around a block-level label, which stretched to the full width of its SettingCard and left the popup floating beside the card rather than under the control. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(rust-client): initialize value_expires_at in the variable models The generated `CreateVariable` / `EditVariable` structs gain the field from openapi.yaml, and client.rs builds both with exhaustive literals. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(frontend): drop extra_args when the variable expiration handler is cleared Clearing the handler nulls the whole setting server-side, extra_args included, but the tab kept its loaded copy. A handler picked afterwards without reloading was persisted with the cleared one's arguments, which the tab does not display. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat: back the variable expiration handler's built-in Slack and Teams destinations Backfills the Slack bot token grant for g/variable_expiration_handler, mirroring 20231016142659 for g/error_handler: the slack_bot folder's extra_perms is written once at Slack connect and never refreshed, and disconnecting leaves the folder behind, so workspaces that already connected Slack cannot pick the grant up from the creation-time list alone. Adds run_variable_expiration_test_job so an admin can exercise the handler on demand rather than waiting for a real expiry, which may be months away. It goes through push_variable_expiration_handler so the test run proves what matters: the handler resolves, and the group can read what it needs, under the same identity and argument shape the sweep uses. Also covers extra_args on the edit endpoint, which the settings tab now writes for the built-ins' channel. The endpoint rebuilds the setting from the request, so an omitted extra_args erases it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * feat(frontend): offer Slack and Teams as variable expiration handlers Gives the variable expiration tab the same no-code destinations the workspace error handler has, so "tell #ops before this credential expires" no longer requires writing a script. A sibling component rather than a fourth mode of ErrorOrRecoveryHandler: that one is shared with the workspace error handler and the three schedule handlers, and its stripped-args list, hub path suffixes and Email tab are all error-shaped. This reuses the pieces that are already generic (SlackConnectionStatus, TeamsConnectionStatus, ChannelSelector, ScriptPicker, SchemaForm) and leaves those five call sites untouched. extra_args stops being an API/CLI-only escape hatch now that the built-ins write their channel into it, so it joins the unsaved-changes comparison and the discard path, normalised through the existing helper that drops the two auto-managed keys. The two hub ids are placeholders until the scripts are pushed to the hub. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * fix(frontend): scope the handler identity notice to the chosen destination The notice told every admin to grant g/variable_expiration_handler write access to the variables it rotates. That is right for a custom handler and wrong for the built-ins, which only post a message and are granted the Slack bot token by migration. Following it for a Slack handler would hand a group write access to the workspace's secrets for no reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * feat(frontend): flag the Slack and Teams handlers as EE Connecting a workspace to Slack or Teams is EE-only (oauth2_oss.rs returns "Slack only available on enterprise"), so on CE those two tabs can never be completed. Says so up front, the way the error/success handler tab does, instead of leaving the user at a "not connected" badge with no working path. Only on those two tabs: a custom script or flow handler is CE. Drops the "Connect Slack first" alert, now that the banner and the connection badge above it already say it twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * chore(backend): regenerate the sqlx cache after the merge The merged workspace_settings column list in change_workspace_id is a new query text, so it needs a new cached entry. Drops the two pre-merge entries it supersedes; both had been left with conflict markers by the merge, since rename/rename markers are eight characters and escape the usual scan. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * fix(cli): narrow the expiry-clear check to a variable that exists remotely Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Do7wJTnL6MG6ngFpCGW4DG * feat(frontend): point the built-in handlers at their published hub scripts Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(backend): regenerate the sqlx cache after the merge Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(frontend): disable the Slack and Teams handler controls without a license Matches the workspace error handler, which greys out its built-in destinations and hides the test button on an unlicensed instance. The custom destination stays editable: unlike the error handler, the variable expiration handler itself is not an EE feature. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * feat: record which destination a variable expiration handler uses handler_configured now counts slack, teams, custom or cleared instead of set or cleared, so usage shows whether the built-in destinations are picked. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(frontend): let the variable expiration handler template run on any worker Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix: guard the variable expiration test endpoint and correct its help text * fix: reuse the error handler's slack arg and built-in path helpers * docs: trim variable expiration sweep and backfill comments * feat: put the variable value expiration under an advanced section * fix: restrict the expiration test job to built-ins and keep expiry on conflict reload * fix: link the expiry hint to the variable's workspace and document built-in test paths * fix: give the expiration sweep its own lock id and reuse double_option * fix: pin the variable expiration presets so the hub-paths test accepts them * feat: let the variable expiration handler set how far ahead it runs * fix: give the notify before expiry setting its own card * feat: remind the variable expiration handler at a set interval * fix: tighten the gap between the Slack channel field and its test button * feat: refuse a value expiry on variables linked to an OAuth account * refactor: reuse the shared handler form for variable expiration * refactor: sweep expiring variables round-robin and check the handler exists * chore: trim comments to the constraints they record * fix: compare expiry dates by moment when deploying a variable draft * refactor: rename value_expires_at to value_valid_until * fix: neutralize variable fields in expiration handler args * fix: reserve the variable_expiration_handler group name for admins * fix: send first expiry notices before reminders * test: pin that a handler failing to start leaves its rows unclaimed * chore: say any hub handler path skips the existence check * fix: empty a pre-existing handler group before granting it the Slack token * docs: correct the registered feature usage counts * fix: let a workspace whose handler failed to start sit out for an hour * fix: send first notices before reminders across workspaces * fix: end a failed handler's wait as soon as it is redeployed * fix: show an expiry-only variable change in the AI fork diff * chore: regenerate workspace tool schemas * test: keep one variable expiration guard per behavior * fix: use the renamed hub expiration handlers and template * feat: carry the variable expiry in windmill-utils-internal 1.8.4 * fix: keep the variable expiry through MCP drafts * chore: bump windmill-utils-internal to 1.8.4 * fix: keep the variable expiry through mcp deploys * fix: disable saving a slack or teams expiry handler without ee * fix: skip the failure mark when the expiry handler was saved mid-sweep * fix: count expiry telemetry only where the expiry changed * test: assert the exact variable expiry in export and cli push tests * fix: stamp an expiry handler failure with the pass's read time * fix: wait for a pending handler lock instead of marking it failed * test: isolate expiry handler tests from the deployed-script cache * fix: retry a failing expiry handler every pass instead of waiting an hour * chore: update ee-repo-ref to b6e23d229966cf0019c0a1926a254fda658d8def This commit updates the EE repository reference after PR #744 was merged in windmill-ee-private. Previous ee-repo-ref: c52c06d145b13a6fb04459e85ca5818bf3c1bff4 New ee-repo-ref: b6e23d229966cf0019c0a1926a254fda658d8def Automated by sync-ee-ref workflow. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: windmill-internal-app[bot] <windmill-internal-app[bot]@users.noreply.github.com> Co-authored-by: hugocasa <hugo@casademont.ch>
1171 lines
40 KiB
Rust
1171 lines
40 KiB
Rust
#[cfg(feature = "async")]
|
|
use futures::FutureExt;
|
|
use windmill_api::{
|
|
apis::{
|
|
configuration::Configuration,
|
|
job_api,
|
|
resource_api::{self, get_resource_value_interpolated},
|
|
variable_api,
|
|
},
|
|
models::{EditResource, GetCompletedJobResultMaybe200Response},
|
|
};
|
|
|
|
use serde::Deserialize;
|
|
use serde_json::{Value, json};
|
|
use std::{
|
|
env::{self, var},
|
|
fmt::Debug,
|
|
time::{Duration, Instant},
|
|
};
|
|
|
|
use crate::{maybe_future::maybe_future::MaybeFuture, ret};
|
|
|
|
#[derive(Debug, Clone)]
|
|
pub struct Windmill {
|
|
pub workspace: String,
|
|
pub token: String,
|
|
pub base_internal_url: String,
|
|
pub client_config: Configuration,
|
|
}
|
|
|
|
impl Windmill {
|
|
/// Creates a new `Windmill` instance with default configuration.
|
|
///
|
|
/// Reads configuration from environment variables:
|
|
/// - `WM_TOKEN` for authentication token
|
|
/// - `WM_WORKSPACE` for workspace name
|
|
/// - `BASE_INTERNAL_URL` for API base URL (appends `/api` automatically)
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Required environment variables are missing
|
|
/// - Environment variables cannot be read
|
|
pub fn default() -> Result<Self, SdkError> {
|
|
Windmill::new(None, None, None)
|
|
}
|
|
|
|
/// Creates a new `Windmill` instance with optional overrides.
|
|
///
|
|
/// Falls back to environment variables for any `None` parameters:
|
|
/// - `WM_TOKEN` if `token` is `None`
|
|
/// - `WM_WORKSPACE` if `workspace` is `None`
|
|
/// - `BASE_INTERNAL_URL` + "/api" if `base_internal_url` is `None`
|
|
///
|
|
/// # Parameters
|
|
/// - `token`: Optional bearer token override
|
|
/// - `workspace`: Optional workspace name override
|
|
/// - `base_internal_url`: Optional base URL override (without `/api` suffix)
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Required environment variables are missing when needed
|
|
/// - Environment variables cannot be read
|
|
pub fn new(
|
|
token: Option<String>,
|
|
workspace: Option<String>,
|
|
base_internal_url: Option<String>,
|
|
) -> Result<Self, SdkError> {
|
|
use env::var;
|
|
let (token, base_internal_url, workspace) = (
|
|
token.or(var("WM_TOKEN").ok()).ok_or(SdkError::BadValue(
|
|
"WM_TOKEN is not set nor was provided in constructor".to_owned(),
|
|
))?,
|
|
base_internal_url
|
|
.or(var("BASE_INTERNAL_URL").ok())
|
|
.ok_or(SdkError::BadValue(
|
|
"BASE_INTERNAL_URL is not set nor was provided in constructor".to_owned(),
|
|
))?
|
|
+ "/api",
|
|
workspace
|
|
.or(var("WM_WORKSPACE").ok())
|
|
.ok_or(SdkError::BadValue(
|
|
"WM_WORKSPACE is not set nor was provided in constructor".to_owned(),
|
|
))?,
|
|
);
|
|
|
|
Ok(Windmill {
|
|
client_config: Configuration {
|
|
// TODO: client: reqwest::blocking::Client::new(), // Use blocking client?
|
|
base_path: base_internal_url.clone(),
|
|
bearer_access_token: Some(token.clone()),
|
|
..Default::default()
|
|
},
|
|
workspace,
|
|
token,
|
|
base_internal_url,
|
|
})
|
|
}
|
|
|
|
/// Retrieves a variable from Windmill, automatically parsing it as JSON/YAML.
|
|
///
|
|
/// This is the convenience version that attempts to parse the variable value as:
|
|
/// 1. JSON (primary attempt)
|
|
/// 2. YAML (fallback if JSON parsing fails)
|
|
/// 3. Raw string (final fallback if both parsings fail)
|
|
///
|
|
/// For better performance when you know the format or don't need parsing,
|
|
/// use [`Self::get_variable_raw`] instead.
|
|
///
|
|
/// # Arguments
|
|
/// * `path` - Variable path (e.g., "u/user/variable_name")
|
|
///
|
|
/// # Example
|
|
/// ```no_run
|
|
///
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::json;
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // For a variable containing JSON: {"key": "value"}
|
|
/// let json_var = wm.get_variable("u/admin/config")?;
|
|
///
|
|
/// // For a variable containing plain text
|
|
/// let text_var = wm.get_variable("u/user/plaintext_note")?;
|
|
///
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// See also: [`Self::get_variable_raw`] for the unparsed version
|
|
pub fn get_variable<'a>(&'a self, path: &'a str) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.get_variable_inner(path));
|
|
}
|
|
|
|
async fn get_variable_inner<'a>(&'a self, path: &'a str) -> Result<Value, SdkError> {
|
|
let raw = self.get_variable_raw_inner(path).await?;
|
|
Ok(serde_json::from_str(&raw)
|
|
.or(serde_yaml::from_str(&raw))
|
|
.unwrap_or(json!(raw)))
|
|
}
|
|
|
|
/// This is the **faster version** when:
|
|
/// - You know the variable contains plain text
|
|
/// - You want to handle parsing yourself
|
|
/// - You need maximum performance
|
|
///
|
|
/// Performance benefit comes from avoiding:
|
|
/// 1. JSON parsing attempt
|
|
/// 2. YAML parsing fallback
|
|
///
|
|
/// # Arguments
|
|
/// * `path` - Variable path (e.g., "u/user/variable_name")
|
|
///
|
|
/// # Example
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::{json, Value};
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // When you need the raw content
|
|
/// let raw_content = wm.get_variable_raw("u/user/custom_format")?;
|
|
///
|
|
/// // When you know it's JSON and want to parse it differently
|
|
/// let json_value: Value = serde_json::from_str(
|
|
/// &wm.get_variable_raw("u/admin/config")?
|
|
/// )?;
|
|
///
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// See also: [`Self::get_variable`] for the auto-parsed version
|
|
pub fn get_variable_raw<'a>(
|
|
&'a self,
|
|
path: &'a str,
|
|
) -> MaybeFuture<'a, Result<String, SdkError>> {
|
|
ret!(self.get_variable_raw_inner(path));
|
|
}
|
|
|
|
async fn get_variable_raw_inner<'a>(&'a self, path: &'a str) -> Result<String, SdkError> {
|
|
let v =
|
|
variable_api::get_variable_value(&self.client_config, &self.workspace, path, None).await?;
|
|
|
|
v.get(1..v.len() - 1)
|
|
.ok_or(SdkError::InternalError(
|
|
"returned value is incorrect".into(),
|
|
))
|
|
.map(|s| s.to_owned())
|
|
}
|
|
|
|
/// Creates or updates a variable in the workspace.
|
|
///
|
|
/// This function provides atomic variable management that:
|
|
/// - Creates a new variable if it doesn't exist
|
|
/// - Updates an existing variable if found
|
|
/// - Handles both regular and secret variables
|
|
///
|
|
/// # Parameters
|
|
/// - `value`: The variable value to set
|
|
/// - `path`: The variable path/identifier
|
|
/// - `is_secret`: Whether to store as a secret (encrypted) variable
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Variable fetch fails for reasons other than "not found"
|
|
/// - Variable creation fails
|
|
/// - Variable update fails
|
|
/// - Underlying API calls fail
|
|
///
|
|
/// # Notes
|
|
/// - For new variables, defaults to empty description
|
|
/// - Updates only modify the value (preserving other metadata)
|
|
/// - Secret status can only be set during creation
|
|
pub fn set_variable<'a>(
|
|
&'a self,
|
|
value: String,
|
|
path: &'a str,
|
|
is_secret: bool,
|
|
) -> MaybeFuture<'a, Result<(), SdkError>> {
|
|
ret!(self.set_variable_inner(value, path, is_secret));
|
|
}
|
|
|
|
async fn set_variable_inner<'a>(
|
|
&'a self,
|
|
value: String,
|
|
path: &'a str,
|
|
is_secret: bool,
|
|
) -> Result<(), SdkError> {
|
|
let res = variable_api::get_variable(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
path,
|
|
None,
|
|
None,
|
|
None,
|
|
)
|
|
.await;
|
|
|
|
if res.is_err() {
|
|
variable_api::create_variable(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
windmill_api::models::CreateVariable {
|
|
path: path.to_owned(),
|
|
value,
|
|
is_secret,
|
|
description: "".to_owned(),
|
|
account: None,
|
|
is_oauth: None,
|
|
expires_at: None,
|
|
value_valid_until: None,
|
|
labels: None,
|
|
ws_specific: None,
|
|
},
|
|
None,
|
|
)
|
|
.await?;
|
|
} else {
|
|
variable_api::update_variable(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
path,
|
|
windmill_api::models::EditVariable {
|
|
path: None,
|
|
value: Some(value),
|
|
is_secret: None,
|
|
description: None,
|
|
value_valid_until: None,
|
|
labels: None,
|
|
ws_specific: None,
|
|
},
|
|
None,
|
|
)
|
|
.await?;
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
/// Fetches and deserializes a resource into a concrete type.
|
|
///
|
|
/// This is the recommended way to access resources when you know the expected type.
|
|
/// For raw JSON access or dynamic typing, use [`Self::get_resource_any`] instead.
|
|
///
|
|
/// # Type Parameters
|
|
/// * `T` - Any type implementing `DeserializeOwned` (most structs with `#[derive(Deserialize)]`)
|
|
///
|
|
/// # Arguments
|
|
/// * `path` - The resource path (e.g., "u/user/resource_name")
|
|
///
|
|
/// # Example
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::{json, Value};
|
|
/// use serde::Deserialize;
|
|
///
|
|
/// #[derive(Deserialize)]
|
|
/// struct DbConfig {
|
|
/// url: String,
|
|
/// pool_size: Option<u32>,
|
|
/// }
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // Directly deserialize to your type
|
|
/// let config: DbConfig = wm.get_resource("u/admin/db_connection")?;
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// See also: [`Self::get_resource_any`] for untyped version
|
|
pub fn get_resource<'a, T: serde::de::DeserializeOwned>(
|
|
&'a self,
|
|
path: &'a str,
|
|
) -> MaybeFuture<'a, Result<T, SdkError>> {
|
|
ret!(self.get_resource_inner(path));
|
|
}
|
|
|
|
async fn get_resource_inner<'a, T: serde::de::DeserializeOwned>(
|
|
&'a self,
|
|
path: &'a str,
|
|
) -> Result<T, SdkError> {
|
|
Ok(serde_json::from_value(
|
|
self.get_resource_any_inner(path).await?,
|
|
)?)
|
|
}
|
|
|
|
/// Fetches a raw JSON [`Value`] from Windmill by path.
|
|
///
|
|
/// Use this when you need the raw JSON structure or don't have a concrete type to deserialize into.
|
|
/// For typed deserialization, prefer [`Self::get_resource`] instead.
|
|
///
|
|
/// # Arguments
|
|
/// * `path` - The resource path (e.g., "u/user/resource_name")
|
|
///
|
|
/// # Example
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // When you need to inspect the raw structure first
|
|
/// let json = wm.get_resource_any("u/admin/db_connection")?;
|
|
///
|
|
/// println!("Url is: {}", json["url"]);
|
|
///
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// See also: [`Self::get_resource`] for typed version
|
|
pub fn get_resource_any<'a>(
|
|
&'a self,
|
|
path: &'a str,
|
|
) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.get_resource_any_inner(path));
|
|
}
|
|
|
|
async fn get_resource_any_inner<'a>(&'a self, path: &'a str) -> Result<Value, SdkError> {
|
|
Ok(
|
|
get_resource_value_interpolated(&self.client_config, &self.workspace, path, None, None)
|
|
.await?,
|
|
)
|
|
}
|
|
|
|
/// Creates or updates a resource in Windmill.
|
|
///
|
|
/// This function sets a resource's value at the specified path, creating it if it doesn't exist
|
|
/// or updating it if it does. The resource will be of the specified type.
|
|
///
|
|
/// # Arguments
|
|
/// * `value` - The value to set for the resource. Use `None` to create an empty resource.
|
|
/// * `path` - The ownership path of the resource (e.g., "u/user/resource_name").
|
|
/// Defines permissions based on Windmill's path prefix system.
|
|
/// * `resource_type` - The type of resource to create (e.g., "postgresql", "smtp").
|
|
/// Must be a pre-existing resource type.
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
///
|
|
/// # fn main() -> anyhow::Result<()> {
|
|
/// let wm = Windmill::default()?;
|
|
/// wm.set_resource(
|
|
/// Some(serde_json::json!({"host": "localhost", "port": 5432})),
|
|
/// "u/admin/database",
|
|
/// "postgresql"
|
|
/// )?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
pub fn set_resource<'a>(
|
|
&'a self,
|
|
value: Option<Value>,
|
|
path: &'a str,
|
|
resource_type: &'a str,
|
|
) -> MaybeFuture<'a, Result<(), SdkError>> {
|
|
ret!(self.set_resource_inner(value, path, resource_type));
|
|
}
|
|
|
|
async fn set_resource_inner<'a>(
|
|
&'a self,
|
|
value: Option<Value>,
|
|
path: &'a str,
|
|
resource_type: &'a str,
|
|
) -> Result<(), SdkError> {
|
|
// if resource_api::get_resource(&self.client_config, &self.workspace, path)
|
|
// .await
|
|
// .is_err()
|
|
if !resource_api::exists_resource(&self.client_config, &self.workspace, path).await? {
|
|
resource_api::create_resource(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
windmill_api::models::CreateResource {
|
|
path: path.to_owned(),
|
|
value,
|
|
description: None,
|
|
resource_type: resource_type.to_owned(),
|
|
labels: None,
|
|
ws_specific: None,
|
|
preserve_on_behalf_of: None,
|
|
},
|
|
// Some(true),
|
|
None,
|
|
)
|
|
.await?;
|
|
} else {
|
|
resource_api::update_resource(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
path,
|
|
EditResource {
|
|
path: None,
|
|
description: None,
|
|
value: Some(value),
|
|
resource_type: Some(resource_type.to_owned()),
|
|
labels: None,
|
|
ws_specific: None,
|
|
preserve_on_behalf_of: None,
|
|
},
|
|
)
|
|
.await?;
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
/// Retrieves and deserializes the current typed state value for a script's execution context.
|
|
///
|
|
/// This is the typed version of [`Self::get_state_any`], automatically deserializing the state
|
|
/// into the specified type `T` that implements [`serde::de::DeserializeOwned`].
|
|
///
|
|
/// # Type Parameter
|
|
/// * `T` - The type to deserialize into (must implement `serde::de::DeserializeOwned`)
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::{json, Value};
|
|
/// use serde::Deserialize;
|
|
///
|
|
/// #[derive(Deserialize)]
|
|
/// struct ScriptState {
|
|
/// counter: i32,
|
|
/// last_run: String,
|
|
/// }
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // Get typed state
|
|
/// let state: ScriptState = wm.get_state()?;
|
|
///
|
|
/// println!("Counter: {}, Last run: {}", state.counter, state.last_run);
|
|
///
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// # Behavior Details
|
|
/// - Uses same state path resolution as [`Self::get_state_any`] (`WM_STATE_PATH_NEW` → `WM_STATE_PATH` fallback)
|
|
/// - Performs runtime type checking during deserialization
|
|
///
|
|
/// # When to Use vs [`Self::get_state_any`]
|
|
/// | Use Case | `get_state<T>` | `get_state_any` |
|
|
/// |------------------------|-------------------------|------------------------|
|
|
/// | Known state structure | ✅ Preferred | ⚠️ Requires manual parsing |
|
|
/// | Dynamic state | ❌ Won't compile | ✅ Works |
|
|
/// | Type safety | ✅ Compile-time checks | ❌ Runtime checks only |
|
|
///
|
|
/// # Notes
|
|
/// - For complex types, derive `Deserialize` using Serde attributes
|
|
/// - Prefer this over [`Self::get_state_any`] when state schema is stable
|
|
/// - State modifications should use corresponding [`Self::set_state`] with matching type
|
|
///
|
|
/// # See Also
|
|
/// - [`Self::get_state_any`] - Untyped state access
|
|
/// - [`Self::set_state`] - For updating typed states
|
|
/// - [Windmill State Management](https://www.windmill.dev/docs/core_concepts/persistent_storage/within_windmill#states)
|
|
pub fn get_state<'a, T: serde::de::DeserializeOwned>(
|
|
&'a self,
|
|
) -> MaybeFuture<'a, Result<T, SdkError>> {
|
|
ret!(self.get_resource_inner(&get_state_path()?));
|
|
}
|
|
|
|
/// Retrieves and deserializes the typed state value from a custom resource path.
|
|
///
|
|
/// This is the same as [`Self::get_state`] but allows overriding the underlying state
|
|
/// resource path. Useful when you want to read/write a different state resource.
|
|
pub fn get_state_at<'a, T: serde::de::DeserializeOwned>(
|
|
&'a self,
|
|
path: &'a str,
|
|
) -> MaybeFuture<'a, Result<T, SdkError>> {
|
|
ret!(self.get_resource_inner(path));
|
|
}
|
|
|
|
/// Retrieves the current state value for a script's execution context.
|
|
///
|
|
/// States persist data between runs of the same script by the same trigger (schedule or user).
|
|
/// This is the untyped version that returns a generic [`Value`].
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::Value;
|
|
/// use serde::Deserialize;
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // Get state (returns serde_json::Value)
|
|
/// let state: Value = wm.get_state_any()?;
|
|
///
|
|
/// // Use with default if empty
|
|
/// let counter = state.as_i64().unwrap_or(0);
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// # Behavior Details
|
|
/// - Automatically uses the script's state path from `WM_STATE_PATH_NEW` (falls back to `WM_STATE_PATH`)
|
|
/// - Returns the full state object stored as a Windmill resource
|
|
/// - State resources are hidden from Workspace view but visible under Resources → States
|
|
///
|
|
/// # Typical Use Cases
|
|
/// 1. Maintaining counters between runs
|
|
/// 2. Storing last execution timestamps
|
|
/// 3. Keeping reference data (like previous API responses)
|
|
///
|
|
/// # Notes
|
|
/// - For typed state access, use `get_state<T>` instead
|
|
/// - States are isolated per script and trigger combination
|
|
/// - Maximum state size: 5MB (compressed)
|
|
///
|
|
/// # See Also
|
|
/// - [`Self::set_state`] - For updating the state
|
|
/// - [Windmill State Management](https://www.windmill.dev/docs/core_concepts/persistent_storage/within_windmill#states)
|
|
pub fn get_state_any<'a>(&'a self) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.get_resource_any_inner(&get_state_path()?));
|
|
}
|
|
|
|
/// Retrieves the untyped state value from a custom resource path.
|
|
///
|
|
/// This is the same as [`Self::get_state_any`] but allows overriding the underlying state
|
|
/// resource path.
|
|
pub fn get_state_any_at<'a>(&'a self, path: &'a str) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.get_resource_any_inner(path));
|
|
}
|
|
|
|
/// Updates or clears the script's persistent state.
|
|
///
|
|
/// # Arguments
|
|
/// * `value` - New state value (`Some(Value)`) or `None` to clear state
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::json;
|
|
///
|
|
/// # async fn example() -> anyhow::Result<()> {
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // Set state
|
|
/// wm.set_state(Some(json!({"count": 42})))?;
|
|
///
|
|
/// // Clear state
|
|
/// wm.set_state(None)?;
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// See also: [`Self::get_state`], [`Self::get_state_any`]
|
|
pub fn set_state<'a>(&'a self, value: Option<Value>) -> MaybeFuture<'a, Result<(), SdkError>> {
|
|
ret!(self.set_resource_inner(value, &get_state_path()?, "state"));
|
|
}
|
|
|
|
/// Updates or clears a state resource at a custom path.
|
|
///
|
|
/// This is the same as [`Self::set_state`] but allows overriding the target state resource
|
|
/// path.
|
|
pub fn set_state_at<'a>(
|
|
&'a self,
|
|
value: Option<Value>,
|
|
path: &'a str,
|
|
) -> MaybeFuture<'a, Result<(), SdkError>> {
|
|
ret!(self.set_resource_inner(value, path, "state"));
|
|
}
|
|
|
|
/// Executes a script synchronously and waits for its completion.
|
|
///
|
|
/// This is a blocking version of `run_script_async` that handles the entire script execution
|
|
/// lifecycle including job scheduling and result waiting.
|
|
///
|
|
/// # Parameters
|
|
/// - `ident`: Script identifier (either path or hash)
|
|
/// - `ident_is_hash`: Whether the identifier is a hash (true) or path (false)
|
|
/// - `args`: JSON arguments to pass to the script
|
|
/// - `scheduled_in_secs`: Optional delay before execution (in seconds)
|
|
/// - `timeout_secs`: Maximum time to wait for job completion (in seconds)
|
|
/// - `verbose`: Whether to print execution details
|
|
/// - `assert_result_is_not_none`: Whether to fail if the result is None
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Script fails to start
|
|
/// - Job times out
|
|
/// - Result assertion fails
|
|
/// - Underlying API calls fail
|
|
pub fn run_script_sync<'a>(
|
|
&'a self,
|
|
ident: &'a str,
|
|
ident_is_hash: bool,
|
|
args: Value,
|
|
scheduled_in_secs: Option<u32>,
|
|
timeout_secs: Option<u64>,
|
|
verbose: bool,
|
|
assert_result_is_not_none: bool,
|
|
) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
if verbose {
|
|
println!("running `{ident}` synchronously with {:?}", &args);
|
|
}
|
|
|
|
ret!(async move {
|
|
let job_id = self
|
|
.run_script_async_inner(ident, ident_is_hash, args, scheduled_in_secs, None)
|
|
.await?;
|
|
self.wait_job_inner(
|
|
&job_id.to_string(),
|
|
timeout_secs,
|
|
verbose,
|
|
assert_result_is_not_none,
|
|
)
|
|
.await
|
|
});
|
|
}
|
|
|
|
/// Same as [`Windmill::run_script_sync`] but allows overriding the worker `tag`
|
|
/// the job runs on.
|
|
///
|
|
/// # Parameters
|
|
/// In addition to the parameters of [`Windmill::run_script_sync`]:
|
|
/// - `tag`: Optional worker tag override (the job is dispatched to workers
|
|
/// listening on this tag instead of the script's default tag)
|
|
pub fn run_script_sync_with_tag<'a>(
|
|
&'a self,
|
|
ident: &'a str,
|
|
ident_is_hash: bool,
|
|
args: Value,
|
|
scheduled_in_secs: Option<u32>,
|
|
timeout_secs: Option<u64>,
|
|
verbose: bool,
|
|
assert_result_is_not_none: bool,
|
|
tag: Option<&'a str>,
|
|
) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
if verbose {
|
|
println!("running `{ident}` synchronously with {:?}", &args);
|
|
}
|
|
|
|
ret!(async move {
|
|
let job_id = self
|
|
.run_script_async_inner(ident, ident_is_hash, args, scheduled_in_secs, tag)
|
|
.await?;
|
|
self.wait_job_inner(
|
|
&job_id.to_string(),
|
|
timeout_secs,
|
|
verbose,
|
|
assert_result_is_not_none,
|
|
)
|
|
.await
|
|
});
|
|
}
|
|
|
|
/// Asynchronously executes a script in Windmill and returns its job UUID.
|
|
///
|
|
/// This function runs a script either by path or by hash, with optional:
|
|
/// - Parent job inheritance (when run within a flow)
|
|
/// - Scheduled execution delay
|
|
/// - Argument passing
|
|
///
|
|
/// # Arguments
|
|
/// * `ident` - Script identifier (path or hash depending on `ident_is_hash`)
|
|
/// * `ident_is_hash` - If true, `ident` is treated as a script hash; if false, as a path
|
|
/// * `args` - JSON arguments to pass to the script (must be an object if using path)
|
|
/// * `scheduled_in_secs` - Optional delay (in seconds) before execution
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// use serde_json::json;
|
|
///
|
|
/// let wm = Windmill::default()?;
|
|
/// let job_id = wm.run_script_async(
|
|
/// "u/user/script_path",
|
|
/// false,
|
|
/// json!({"param1": "value1"}),
|
|
/// Some(10) // Run after 10 seconds
|
|
/// )?;
|
|
///
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
///
|
|
/// # Behavior Details
|
|
/// - **Automatic Job Inheritance**:
|
|
/// - Detects `WM_JOB_ID` env var → sets as `parent_job`
|
|
/// - Detects `WM_ROOT_FLOW_JOB_ID` env var → sets as `root_job`
|
|
/// - **Scheduled Execution**:
|
|
/// - When `scheduled_in_secs` is provided, sets `scheduled_in_secs` in args
|
|
/// - **Argument Handling**:
|
|
/// - For path-based execution (`ident_is_hash=false`), args must be a JSON object
|
|
/// - For hash-based execution, args can be any valid JSON value
|
|
///
|
|
/// # Errors
|
|
/// - [`SdkError::BadValue`] if path-based execution receives non-object arguments
|
|
/// - API errors from Windmill's backend
|
|
pub fn run_script_async<'a>(
|
|
&'a self,
|
|
ident: &'a str,
|
|
ident_is_hash: bool,
|
|
args: Value,
|
|
scheduled_in_secs: Option<u32>,
|
|
) -> MaybeFuture<'a, Result<uuid::Uuid, SdkError>> {
|
|
ret!(self.run_script_async_inner(ident, ident_is_hash, args, scheduled_in_secs, None));
|
|
}
|
|
|
|
/// Same as [`Windmill::run_script_async`] but allows overriding the worker `tag`
|
|
/// the job runs on.
|
|
///
|
|
/// # Arguments
|
|
/// In addition to the arguments of [`Windmill::run_script_async`]:
|
|
/// * `tag` - Optional worker tag override (the job is dispatched to workers
|
|
/// listening on this tag instead of the script's default tag)
|
|
pub fn run_script_async_with_tag<'a>(
|
|
&'a self,
|
|
ident: &'a str,
|
|
ident_is_hash: bool,
|
|
args: Value,
|
|
scheduled_in_secs: Option<u32>,
|
|
tag: Option<&'a str>,
|
|
) -> MaybeFuture<'a, Result<uuid::Uuid, SdkError>> {
|
|
ret!(self.run_script_async_inner(ident, ident_is_hash, args, scheduled_in_secs, tag));
|
|
}
|
|
|
|
async fn run_script_async_inner<'a>(
|
|
&'a self,
|
|
ident: &'a str,
|
|
ident_is_hash: bool,
|
|
mut args: Value,
|
|
scheduled_in_secs: Option<u32>,
|
|
tag: Option<&'a str>,
|
|
) -> Result<uuid::Uuid, SdkError> {
|
|
if let Ok(parent_job) = var("WM_JOB_ID") {
|
|
args["parent_job"] = json!(parent_job);
|
|
}
|
|
|
|
if let Ok(root_job) = var("WM_ROOT_FLOW_JOB_ID") {
|
|
args["root_job"] = json!(root_job);
|
|
}
|
|
|
|
if let Some(scheduled_in_secs) = scheduled_in_secs {
|
|
args["scheduled_in_secs"] = json!(scheduled_in_secs);
|
|
}
|
|
|
|
// The `None`s below map positionally to the query params of the generated
|
|
// job API. The 5th one is the worker `tag` override (after scheduled_for,
|
|
// scheduled_in_secs, skip_preprocessor and parent_job).
|
|
let uuid = if ident_is_hash {
|
|
job_api::run_script_by_hash(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
ident,
|
|
args,
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
tag,
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
)
|
|
.await?
|
|
} else {
|
|
job_api::run_script_by_path(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
ident,
|
|
args.as_object()
|
|
.ok_or(SdkError::BadValue(format!(
|
|
"Args should be Object, but it is: {}",
|
|
args
|
|
)))?
|
|
.clone()
|
|
.into_iter()
|
|
.collect(),
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
tag,
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
)
|
|
.await?
|
|
};
|
|
Ok(uuid)
|
|
}
|
|
|
|
/// Waits for a job to complete and returns its result.
|
|
///
|
|
/// This function provides both synchronous and asynchronous interfaces for waiting
|
|
/// on job completion, with timeout handling and result validation.
|
|
///
|
|
/// # Parameters
|
|
/// - `job_id`: The ID of the job to wait for
|
|
/// - `timeout_secs`: Maximum time to wait (in seconds) before cancelling the job
|
|
/// - `verbose`: Whether to print progress information
|
|
/// - `assert_result_is_not_none`: Whether to fail if the job returns no result
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Job fails or times out
|
|
/// - Result assertion fails when `assert_result_is_not_none` is true
|
|
/// - Underlying API calls fail
|
|
///
|
|
/// # Behavior
|
|
/// 1. Polls job status at 500ms intervals
|
|
/// 2. Cancels job if timeout is reached
|
|
/// 3. Validates success status and optional result presence
|
|
/// 4. Returns either the result or appropriate error
|
|
pub fn wait_job<'a>(
|
|
&'a self,
|
|
job_id: &'a str,
|
|
timeout_secs: Option<u64>,
|
|
verbose: bool,
|
|
assert_result_is_not_none: bool,
|
|
) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.wait_job_inner(job_id, timeout_secs, verbose, assert_result_is_not_none));
|
|
}
|
|
|
|
async fn wait_job_inner<'a>(
|
|
&'a self,
|
|
job_id: &'a str,
|
|
timeout_secs: Option<u64>,
|
|
verbose: bool,
|
|
assert_result_is_not_none: bool,
|
|
) -> Result<Value, SdkError> {
|
|
let start = Instant::now();
|
|
loop {
|
|
if let Some(timeout) = timeout_secs {
|
|
if start.elapsed().as_secs() > timeout {
|
|
println!("WARN: reached timeout for {job_id}. Cancelling the job.");
|
|
job_api::cancel_queued_job(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
job_id,
|
|
windmill_api::models::CancelQueuedJobRequest {
|
|
reason: Some("reached timeout".into()),
|
|
},
|
|
)
|
|
.await?;
|
|
}
|
|
}
|
|
let GetCompletedJobResultMaybe200Response {
|
|
completed,
|
|
result,
|
|
success,
|
|
started,
|
|
} = job_api::get_completed_job_result_maybe(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
job_id,
|
|
Some(true),
|
|
)
|
|
.await?;
|
|
|
|
if matches!(started, Some(false)) && verbose {
|
|
println!("INFO: job {job_id} has not started yet");
|
|
}
|
|
|
|
if completed {
|
|
if matches!(success, Some(true)) {
|
|
if result.is_none() && assert_result_is_not_none {
|
|
return Err(SdkError::ExecutionError("Result was None".into()));
|
|
}
|
|
return Ok(result.unwrap_or_default());
|
|
} else {
|
|
return Err(SdkError::ExecutionError(format!(
|
|
"Job {job_id} was not successful: {:?}",
|
|
result
|
|
)));
|
|
}
|
|
}
|
|
if verbose {
|
|
println!("INFO: sleeping 0.5 seconds for {job_id}");
|
|
}
|
|
tokio::time::sleep(Duration::from_millis(500)).await;
|
|
}
|
|
}
|
|
|
|
/// Retrieves the current status of a Windmill job by its UUID.
|
|
///
|
|
/// This function queries the Windmill backend to determine whether a job is:
|
|
/// - Waiting to be executed
|
|
/// - Currently running
|
|
/// - Already completed
|
|
///
|
|
/// # Arguments
|
|
/// * `job_id` - The UUID of the job to check (format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
|
|
///
|
|
/// # Job Lifecycle States
|
|
/// - **Waiting**: Job is queued but hasn't started execution
|
|
/// - **Running**: Job is currently being executed
|
|
/// - **Completed**: Job has finished (successfully or with errors)
|
|
pub fn get_job_status<'a>(
|
|
&'a self,
|
|
job_id: &'a str,
|
|
) -> MaybeFuture<'a, Result<JobStatus, SdkError>> {
|
|
ret!(self.get_job_status_inner(job_id));
|
|
}
|
|
|
|
async fn get_job_status_inner<'a>(&'a self, job_id: &'a str) -> Result<JobStatus, SdkError> {
|
|
let job = job_api::get_job(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
job_id,
|
|
Some(true),
|
|
Some(true),
|
|
None,
|
|
)
|
|
.await?;
|
|
|
|
Ok(match job {
|
|
windmill_api::models::Job::JobOneOf(..) => JobStatus::Completed,
|
|
windmill_api::models::Job::JobOneOf1(job_one_of1) => {
|
|
if job_one_of1.running {
|
|
JobStatus::Running
|
|
} else {
|
|
JobStatus::Waiting
|
|
}
|
|
}
|
|
})
|
|
}
|
|
|
|
/// Retrieves the result of a completed job.
|
|
///
|
|
/// This provides both synchronous and asynchronous interfaces for fetching
|
|
/// the final result of a successfully completed job.
|
|
///
|
|
/// # Parameters
|
|
/// - `job_id`: The ID of the completed job to fetch results for
|
|
///
|
|
/// # Errors
|
|
/// Returns `SdkError` if:
|
|
/// - Job is not found
|
|
/// - Job failed to complete successfully
|
|
/// - Underlying API calls fail
|
|
/// - Result cannot be parsed
|
|
///
|
|
/// # Notes
|
|
/// - Only works for jobs that have already completed
|
|
/// - For pending/running jobs, use `wait_job` instead
|
|
/// - Does not handle timeouts or polling - assumes job is already complete
|
|
pub fn get_result<'a>(&'a self, job_id: &'a str) -> MaybeFuture<'a, Result<Value, SdkError>> {
|
|
ret!(self.get_result_inner(job_id));
|
|
}
|
|
|
|
async fn get_result_inner<'a>(&'a self, job_id: &'a str) -> Result<Value, SdkError> {
|
|
Ok(job_api::get_completed_job_result(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
job_id,
|
|
None,
|
|
None,
|
|
None,
|
|
None,
|
|
)
|
|
.await?)
|
|
}
|
|
|
|
/// Updates the progress percentage of a running Windmill job.
|
|
///
|
|
/// This function allows scripts to report their execution progress (0-100%) back to the Windmill UI.
|
|
/// Progress updates are visible in both the jobs dashboard and flow visualizations.
|
|
///
|
|
/// # Arguments
|
|
/// * `value` - Progress percentage (0-100)
|
|
/// * `job_id` - Optional job UUID. If None, uses current job's ID from `WM_JOB_ID` environment variable
|
|
///
|
|
/// # Examples
|
|
/// ```no_run
|
|
/// use wmill::Windmill;
|
|
/// # fn main () -> anyhow::Result<()>{
|
|
/// let wm = Windmill::default()?;
|
|
///
|
|
/// // Report progress for current job
|
|
/// wm.set_progress(25, None)?;
|
|
/// # Ok(())
|
|
/// # }
|
|
///
|
|
/// ```
|
|
///
|
|
/// # Behavior Details
|
|
/// - Automatically handles flow context by detecting parent job ID
|
|
/// - Progress updates are reflected in real-time in the Windmill UI
|
|
/// - Typical usage pattern:
|
|
/// ```ignore
|
|
/// for (i, item) in items.iter().enumerate() {
|
|
/// process(item);
|
|
/// let progress = ((i + 1) * 100 / items.len()) as i32;
|
|
/// wmill.set_progress(progress, None).await?;
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// # Notes
|
|
/// - Only affects jobs that are currently running
|
|
/// - Progress values outside 0-99 range are clamped by the server
|
|
/// - Progress cannot decrease
|
|
/// - For flows, updates the progress of both the step and parent flow
|
|
///
|
|
/// # See Also
|
|
/// - [Flow Progress Tracking](https://www.windmill.dev/docs/advanced/explicit_progress)
|
|
/// - [`Self::get_progress`] - For reading job progress
|
|
pub fn set_progress<'a>(
|
|
&'a self,
|
|
value: u32,
|
|
job_id: Option<String>,
|
|
) -> MaybeFuture<'a, Result<(), SdkError>> {
|
|
let f = async move {
|
|
let job_id = job_id.unwrap_or(var("WM_JOB_ID")?);
|
|
let job = job_api::get_job(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
&job_id,
|
|
Some(true),
|
|
Some(true),
|
|
None,
|
|
)
|
|
.await?;
|
|
|
|
let flow_id = match job {
|
|
windmill_api::models::Job::JobOneOf(job) => job.parent_job,
|
|
windmill_api::models::Job::JobOneOf1(job) => job.parent_job,
|
|
};
|
|
|
|
windmill_api::apis::metrics_api::set_job_progress(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
&job_id,
|
|
windmill_api::models::SetJobProgressRequest {
|
|
percent: Some(value as i32),
|
|
flow_job_id: flow_id,
|
|
},
|
|
)
|
|
.await?;
|
|
Ok(())
|
|
};
|
|
ret!(f);
|
|
}
|
|
|
|
/// Retrieves the current progress percentage of a Windmill job.
|
|
///
|
|
/// This function queries the Windmill backend to get the execution progress (0-100%)
|
|
/// of either a specific job or the current job context.
|
|
///
|
|
/// # Arguments
|
|
/// * `job_id` - Optional job UUID. If `None`, uses current job's ID from `WM_JOB_ID` env var
|
|
///
|
|
/// # See Also
|
|
/// - [Flow Progress Tracking](https://www.windmill.dev/docs/advanced/explicit_progress)
|
|
/// - [`Self::set_progress`] - For updating job progress
|
|
pub fn get_progress<'a>(
|
|
&'a self,
|
|
job_id: Option<String>,
|
|
) -> MaybeFuture<'a, Result<u32, SdkError>> {
|
|
let f = async move {
|
|
let job_id = job_id.unwrap_or(var("WM_JOB_ID")?);
|
|
Ok(windmill_api::apis::metrics_api::get_job_progress(
|
|
&self.client_config,
|
|
&self.workspace,
|
|
&job_id,
|
|
)
|
|
.await
|
|
.map(|v| v as u32)?)
|
|
};
|
|
ret!(f);
|
|
}
|
|
|
|
/// Executes an API call in either asynchronous or synchronous mode based on compilation context.
|
|
///
|
|
/// This function serves as a bridge between async and sync code, automatically adapting its behavior:
|
|
/// - With `async` feature: Returns a boxed future for later await
|
|
/// - Without `async` feature: Blocks immediately using the global runtime
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ## Async usage (with `async` feature)
|
|
/// ```ignore
|
|
/// use wmill::Windmill;
|
|
/// # #[tokio::main]
|
|
/// # async fn main() -> anyhow::Result<()>{
|
|
/// let wm = Windmill::default()?;
|
|
/// let user = wm.call_api(wmill::apis::admin_api::get_user(&wm.client_config, &wm.workspace, "Bob"))?;
|
|
/// println!("User details: {:?}", user);
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// ## Sync usage (without `async` feature)
|
|
/// ```ignore
|
|
/// use wmill::Windmill;
|
|
/// let wm = Windmill::new(Some("<TOKEN>".into()), Some("admins".into()), Some("http://localhost:5000/api".into()))?;
|
|
/// let user = wm.call_api(wmill::apis::admin_api::get_user(&wm.client_config, &wm.workspace, "Bob"));
|
|
/// println!("User details: {:?}", user);
|
|
/// # Ok::<(), wmill::SdkError>(())
|
|
/// ```
|
|
pub fn call_api<'a, T>(
|
|
&'a self,
|
|
callback: impl Future<Output = T> + std::marker::Send + 'a,
|
|
) -> MaybeFuture<'a, T> {
|
|
ret!(callback);
|
|
}
|
|
|
|
// pub fn get_version() {}
|
|
}
|
|
|
|
pub enum JobStatus {
|
|
Running,
|
|
Waiting,
|
|
Completed,
|
|
}
|
|
|
|
fn get_state_path() -> Result<String, SdkError> {
|
|
Ok(var("WM_STATE_PATH_NEW").unwrap_or(var("WM_STATE_PATH")?))
|
|
}
|
|
|
|
#[derive(thiserror::Error, Debug)]
|
|
pub enum SdkError {
|
|
#[error("Error: {0}")]
|
|
Serde(#[from] serde_json::Error),
|
|
#[error("Having troubles reading Env Variable: {0}")]
|
|
VarError(#[from] std::env::VarError),
|
|
#[error("Api error: {0}")]
|
|
ApiError(String),
|
|
#[error("Internal Error: {0}")]
|
|
InternalError(String),
|
|
#[error("Specified value is incorrect: {0}")]
|
|
BadValue(String),
|
|
#[error("{0}")]
|
|
ExecutionError(String),
|
|
}
|
|
impl<T: for<'a> Deserialize<'a>> From<windmill_api::apis::Error<T>> for SdkError {
|
|
fn from(value: windmill_api::apis::Error<T>) -> Self {
|
|
Self::ApiError(value.to_string())
|
|
}
|
|
}
|