hatchet-client 0.1.0

Rust SDK for Hatchet: run workers and trigger tasks
Documentation
//! Assembling the `StepActionEvent`s a worker reports for a run.
//!
//! Pure functions: everything the engine needs to match a report to its run
//! is copied from the action that asked for it, so a report can be built
//! without holding any of the run's state.

use std::time::SystemTime;

use hatchet_proto::prost_types::Timestamp;
use hatchet_proto::root::{
    AssignedAction, BatchActionEvent, BatchActionEventItem, StepActionEvent, StepActionEventType,
};
use serde_json::Value;

use crate::TaskError;
use crate::batch::BatchMemberId;

/// The run has begun. The engine wants no payload with it.
pub(crate) fn started(action: &AssignedAction, worker_id: &str) -> StepActionEvent {
    event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeStarted,
        String::new(),
        None,
    )
}

/// The run succeeded; the payload is the task's output as JSON.
pub(crate) fn completed(
    action: &AssignedAction,
    worker_id: &str,
    output: &Value,
) -> StepActionEvent {
    event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeCompleted,
        output.to_string(),
        None,
    )
}

/// The run failed; the payload is the message, encoded as a JSON string.
///
/// `should_not_retry` is only ever `Some(true)`: the engine reads the absent
/// flag as "retry as configured", and saying `Some(false)` would be a claim
/// this SDK has no business making.
pub(crate) fn failed(
    action: &AssignedAction,
    worker_id: &str,
    error: &TaskError,
) -> StepActionEvent {
    event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeFailed,
        Value::String(error.message().to_string()).to_string(),
        (!error.is_retryable()).then_some(true),
    )
}

/// Every member of a batch has begun.
///
/// One report for the whole batch, sent before the handler is called, exactly
/// as both official SDKs do (`pkg/worker/worker.go:867-885`). The engine wants
/// no payload with a STARTED (`dispatcher.proto`, "unused for
/// STARTED/CANCELLED"), and this sends the same empty string an ordinary
/// [`started`] report carries.
pub(crate) fn batch_started(
    action: &AssignedAction,
    worker_id: &str,
    members: &[BatchMemberId],
) -> BatchActionEvent {
    batch_event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeStarted,
        members
            .iter()
            .map(|id| BatchActionEventItem {
                task_run_external_id: id.clone(),
                event_payload: String::new(),
                retry_count: None,
                should_not_retry: None,
            })
            .collect(),
    )
}

/// These members of the batch succeeded; each payload is that member's own
/// output as JSON.
pub(crate) fn batch_completed(
    action: &AssignedAction,
    worker_id: &str,
    items: &[(BatchMemberId, Value)],
) -> BatchActionEvent {
    batch_event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeCompleted,
        items
            .iter()
            .map(|(id, output)| BatchActionEventItem {
                task_run_external_id: id.clone(),
                event_payload: output.to_string(),
                retry_count: None,
                should_not_retry: None,
            })
            .collect(),
    )
}

/// These members of the batch failed; each payload is that member's message,
/// encoded as a JSON string exactly as [`failed`] encodes an ordinary run's.
///
/// `should_not_retry` is per member and only ever `Some(true)`, for the same
/// reason it is on an ordinary run: the absent flag means "retry as
/// configured", and `Some(false)` would be a claim this SDK has no business
/// making.
pub(crate) fn batch_failed(
    action: &AssignedAction,
    worker_id: &str,
    items: &[(BatchMemberId, TaskError)],
) -> BatchActionEvent {
    batch_event(
        action,
        worker_id,
        StepActionEventType::StepEventTypeFailed,
        items
            .iter()
            .map(|(id, error)| BatchActionEventItem {
                task_run_external_id: id.clone(),
                event_payload: Value::String(error.message().to_string()).to_string(),
                retry_count: None,
                should_not_retry: (!error.is_retryable()).then_some(true),
            })
            .collect(),
    )
}

/// The half every batch report shares.
///
/// `job_id` is copied from the assignment, which the engine says is shared by
/// every item in the batch and which the official Go SDK copies the same way
/// (`pkg/worker/worker.go:940-951`). Measured against every engine that
/// batches, it arrives **empty**, and the engine accepts the empty string back.
///
/// `retry_count` is deliberately left off every item: a batch action's own
/// retry count is nobody's in particular, and the engine falls back to each
/// task's current one when the field is unset.
fn batch_event(
    action: &AssignedAction,
    worker_id: &str,
    event_type: StepActionEventType,
    items: Vec<BatchActionEventItem>,
) -> BatchActionEvent {
    BatchActionEvent {
        worker_id: worker_id.to_string(),
        job_id: action.job_id.clone(),
        action_id: action.action_id.clone(),
        batch_id: action.batch_id.clone(),
        event_timestamp: Some(Timestamp::from(SystemTime::now())),
        event_type: event_type as i32,
        items,
    }
}

fn event(
    action: &AssignedAction,
    worker_id: &str,
    event_type: StepActionEventType,
    event_payload: String,
    should_not_retry: Option<bool>,
) -> StepActionEvent {
    StepActionEvent {
        worker_id: worker_id.to_string(),
        job_id: action.job_id.clone(),
        job_run_id: action.job_run_id.clone(),
        task_id: action.task_id.clone(),
        task_run_external_id: action.task_run_external_id.clone(),
        action_id: action.action_id.clone(),
        // The engine stamps its own receipt time too; this is when the worker
        // saw it happen.
        event_timestamp: Some(Timestamp::from(SystemTime::now())),
        event_type: event_type as i32,
        event_payload,
        // Reporting the attempt the engine asked for keeps a late report from
        // being attributed to a newer attempt.
        retry_count: Some(action.retry_count),
        should_not_retry,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    /// An action with every id field the engine expects back, so a report
    /// that drops one is visible.
    fn action() -> AssignedAction {
        AssignedAction {
            job_id: "job-1".to_string(),
            job_run_id: "job-run-1".to_string(),
            task_id: "task-1".to_string(),
            task_run_external_id: "run-1".to_string(),
            action_id: "pipeline:build".to_string(),
            retry_count: 2,
            ..AssignedAction::default()
        }
    }

    #[test]
    fn started_copies_the_ids_and_has_an_empty_payload() {
        let event = started(&action(), "worker-1");

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeStarted as i32
        );
        assert_eq!(event.worker_id, "worker-1");
        assert_eq!(event.job_id, "job-1");
        assert_eq!(event.job_run_id, "job-run-1");
        assert_eq!(event.task_id, "task-1");
        assert_eq!(event.task_run_external_id, "run-1");
        assert_eq!(event.action_id, "pipeline:build");
        assert_eq!(event.retry_count, Some(2));
        assert_eq!(event.should_not_retry, None);
        assert!(event.event_timestamp.is_some());
        assert_eq!(event.event_payload, "");
    }

    #[test]
    fn completed_carries_the_output_as_json() {
        let event = completed(&action(), "worker-1", &json!({"pr": null}));

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeCompleted as i32
        );
        assert_eq!(event.event_payload, r#"{"pr":null}"#);
        assert_eq!(event.task_run_external_id, "run-1");
        assert_eq!(event.retry_count, Some(2));
        assert_eq!(event.should_not_retry, None);
        assert!(event.event_timestamp.is_some());
    }

    #[test]
    fn failed_encodes_the_message_as_a_json_string() {
        let event = failed(&action(), "worker-1", &TaskError::new("bad \"thing\""));

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeFailed as i32
        );
        assert_eq!(event.event_payload, "\"bad \\\"thing\\\"\"");
        assert_eq!(event.should_not_retry, None);
        assert_eq!(event.task_run_external_id, "run-1");
        assert_eq!(event.retry_count, Some(2));
        assert!(event.event_timestamp.is_some());
    }

    /// A blank message is how the *engine* records a task it cancelled, and
    /// the client side tells a cancellation from a failure by exactly that
    /// shape (`crate::runs::cancelled_shape`). Encoding the message as a JSON
    /// string is what keeps the two apart: a failure with nothing to say goes
    /// out as `"\"\""`, which is not blank, so it is never mistaken for
    /// someone's decision to stop the run. Pinned here because that safety
    /// now rests on it.
    #[test]
    fn a_blank_failure_message_is_never_sent_blank() {
        for blank in ["", "   ", "\n"] {
            let event = failed(&action(), "worker-1", &TaskError::new(blank));
            assert_eq!(
                event.event_payload,
                Value::String(blank.to_string()).to_string(),
                "{blank:?}"
            );
            assert!(
                !event.event_payload.trim().is_empty(),
                "a blank message must not go out blank: {:?}",
                event.event_payload
            );
        }
        assert_eq!(
            failed(&action(), "worker-1", &TaskError::new("")).event_payload,
            "\"\"",
        );
    }

    /// A `START_BATCH` as an engine really sends one: a batch id, and nothing
    /// in any of the per-run fields.
    fn batch_action() -> AssignedAction {
        AssignedAction {
            action_id: "pipeline:embed".to_string(),
            batch_id: Some("b-1".to_string()),
            retry_count: 7,
            ..AssignedAction::default()
        }
    }

    #[test]
    fn a_batch_started_report_names_every_member_and_carries_no_payload() {
        let event = batch_started(
            &batch_action(),
            "worker-1",
            &["a".to_string(), "b".to_string()],
        );

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeStarted as i32
        );
        assert_eq!(event.items.len(), 2);
        assert_eq!(event.items[0].task_run_external_id, "a");
        assert_eq!(event.items[1].task_run_external_id, "b");
        assert!(event.items.iter().all(|item| item.event_payload.is_empty()));
        assert!(
            event
                .items
                .iter()
                .all(|item| item.should_not_retry.is_none())
        );
    }

    #[test]
    fn a_batch_report_carries_the_shared_ids_and_no_per_item_retry_count() {
        let event = batch_completed(
            &batch_action(),
            "worker-1",
            &[("a".to_string(), json!({"n": 1}))],
        );

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeCompleted as i32
        );
        assert_eq!(event.worker_id, "worker-1");
        assert_eq!(event.action_id, "pipeline:embed");
        assert_eq!(event.batch_id.as_deref(), Some("b-1"));
        // Empty on the assignment, and copied as it stands rather than invented.
        assert_eq!(event.job_id, "");
        assert!(event.event_timestamp.is_some());
        assert_eq!(event.items[0].event_payload, r#"{"n":1}"#);
        // The assignment's retry count is the batch's, not this member's: the
        // engine falls back to each task's own when the field is unset.
        assert_eq!(event.items[0].retry_count, None);
        assert_eq!(event.items[0].should_not_retry, None);
    }

    #[test]
    fn batch_failures_encode_the_message_as_a_json_string_per_member() {
        let event = batch_failed(
            &batch_action(),
            "worker-1",
            &[
                ("a".to_string(), TaskError::new("bad \"thing\"")),
                ("b".to_string(), TaskError::non_retryable("never again")),
            ],
        );

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeFailed as i32
        );
        assert_eq!(event.items[0].event_payload, "\"bad \\\"thing\\\"\"");
        assert_eq!(event.items[0].should_not_retry, None);
        assert_eq!(event.items[1].event_payload, "\"never again\"");
        assert_eq!(event.items[1].should_not_retry, Some(true));
    }

    #[test]
    fn non_retryable_failures_say_so() {
        let event = failed(
            &action(),
            "worker-1",
            &TaskError::non_retryable("no point trying again"),
        );

        assert_eq!(
            event.event_type,
            StepActionEventType::StepEventTypeFailed as i32
        );
        assert_eq!(event.should_not_retry, Some(true));
        assert_eq!(event.event_payload, "\"no point trying again\"");
    }
}