hatchet-sdk 0.0.1 → 0.1.0.pre.alpha

data/lib/hatchet/features/runs.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'timeout'
+
+module Hatchet
+  module Features
+    # Filter options for listing task runs
+    class RunFilter
+      attr_accessor :since, :until_time, :statuses, :workflow_ids, :additional_metadata
+
+      def initialize(since:, until_time: nil, statuses: nil, workflow_ids: nil, additional_metadata: nil)
+        @since = since
+        @until_time = until_time
+        @statuses = statuses
+        @workflow_ids = workflow_ids
+        @additional_metadata = additional_metadata
+      end
+    end
+
+    # Options for bulk cancel and replay operations
+    class BulkCancelReplayOpts
+      attr_accessor :ids, :filters
+
+      def initialize(ids: nil, filters: nil)
+        raise ArgumentError, "ids or filters must be set" if !ids && !filters
+        raise ArgumentError, "ids and filters cannot both be set" if ids && filters
+        
+        @ids = ids
+        @filters = filters
+      end
+
+      def v1_task_filter
+        return nil unless @filters
+
+        HatchetSdkRest::V1TaskFilter.new(
+          since: @filters.since,
+          until: @filters.until_time,
+          statuses: @filters.statuses,
+          workflow_ids: @filters.workflow_ids,
+          additional_metadata: maybe_additional_metadata_to_kv(@filters.additional_metadata)
+        )
+      end
+
+      def to_cancel_request
+        HatchetSdkRest::V1CancelTaskRequest.new(
+          external_ids: @ids,
+          filter: v1_task_filter
+        )
+      end
+
+      def to_replay_request
+        HatchetSdkRest::V1ReplayTaskRequest.new(
+          external_ids: @ids,
+          filter: v1_task_filter
+        )
+      end
+
+      private
+
+      def maybe_additional_metadata_to_kv(metadata)
+        return nil unless metadata
+        metadata.map { |k, v| { key: k.to_s, value: v.to_s } }
+      end
+    end
+
+    # Runs client for interacting with Hatchet workflow run management API
+    #
+    # This class provides a high-level interface for creating and managing workflow runs
+    # in the Hatchet system. It wraps the generated REST API client with a more
+    # convenient Ruby interface.
+    #
+    # @example Creating a workflow run
+    #   runs = Features::Runs.new(rest_client, config)
+    #   response = runs.create(
+    #     name: "my-workflow",
+    #     input: { key: "value" },
+    #     additional_metadata: { source: "api" }
+    #   )
+    #
+    # @since 0.1.0
+    class Runs
+      # Re-export commonly used workflow run classes for convenience
+      TriggerWorkflowRunRequest = ::HatchetSdkRest::V1TriggerWorkflowRunRequest
+      WorkflowRunDetails = ::HatchetSdkRest::V1WorkflowRunDetails
+      TaskSummary = ::HatchetSdkRest::V1TaskSummary
+      TaskSummaryList = ::HatchetSdkRest::V1TaskSummaryList
+      TaskStatus = ::HatchetSdkRest::V1TaskStatus
+      
+      DEFAULT_SINCE_DAYS = 1
+      LARGE_DATE_RANGE_WARNING_DAYS = 7
+
+      # Initializes a new Runs client instance
+      #
+      # @param rest_client [Object] The configured REST client for API communication
+      # @param config [Hatchet::Config] The Hatchet configuration containing tenant_id and other settings
+      # @return [void]
+      # @since 0.1.0
+      def initialize(rest_client, config)
+        @rest_client = rest_client
+        @config = config
+        @workflow_runs_api = HatchetSdkRest::WorkflowRunsApi.new(rest_client)
+        @task_api = HatchetSdkRest::TaskApi.new(rest_client)
+      end
+
+      # Get task run details for a given task run ID
+      #
+      # @param task_run_id [String] The ID of the task run to retrieve details for
+      # @return [HatchetSdkRest::V1TaskSummary] Task run details for the specified task run ID
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def get_task_run(task_run_id)
+        @task_api.v1_task_get(task_run_id)
+      end
+
+      # Get workflow run details for a given workflow run ID
+      #
+      # @param workflow_run_id [String] The ID of the workflow run to retrieve details for
+      # @return [HatchetSdkRest::V1WorkflowRunDetails] Workflow run details for the specified workflow run ID
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def get(workflow_run_id)
+        @workflow_runs_api.v1_workflow_run_get(workflow_run_id.to_s)
+      end
+
+      # Get workflow run status for a given workflow run ID
+      #
+      # @param workflow_run_id [String] The ID of the workflow run to retrieve status for
+      # @return [HatchetSdkRest::V1TaskStatus] The task status
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def get_status(workflow_run_id)
+        @workflow_runs_api.v1_workflow_run_get_status(workflow_run_id)
+      end
+
+      # List task runs according to a set of filters, paginating through days
+      #
+      # @param since [Time, nil] The start time for filtering task runs
+      # @param only_tasks [Boolean] Whether to only list task runs
+      # @param offset [Integer, nil] The offset for pagination
+      # @param limit [Integer, nil] The maximum number of task runs to return
+      # @param statuses [Array<HatchetSdkRest::V1TaskStatus>, nil] The statuses to filter task runs by
+      # @param until_time [Time, nil] The end time for filtering task runs
+      # @param additional_metadata [Hash<String, String>, nil] Additional metadata to filter task runs by
+      # @param workflow_ids [Array<String>, nil] The workflow IDs to filter task runs by
+      # @param worker_id [String, nil] The worker ID to filter task runs by
+      # @param parent_task_external_id [String, nil] The parent task external ID to filter task runs by
+      # @param triggering_event_external_id [String, nil] The event id that triggered the task run
+      # @return [Array<HatchetSdkRest::V1TaskSummary>] A list of task runs matching the specified filters
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def list_with_pagination(
+        since: nil,
+        only_tasks: false,
+        offset: nil,
+        limit: nil,
+        statuses: nil,
+        until_time: nil,
+        additional_metadata: nil,
+        workflow_ids: nil,
+        worker_id: nil,
+        parent_task_external_id: nil,
+        triggering_event_external_id: nil
+      )
+        date_ranges = partition_date_range(
+          since: since || (Time.now - DEFAULT_SINCE_DAYS * 24 * 60 * 60),
+          until_time: until_time || Time.now
+        )
+
+        responses = date_ranges.map do |start_time, end_time|
+          @workflow_runs_api.v1_workflow_run_list(
+            @config.tenant_id,
+            start_time.utc.iso8601,
+            only_tasks,
+            {
+              offset: offset,
+              limit: limit,
+              statuses: statuses,
+              until: end_time.utc.iso8601,
+              additional_metadata: maybe_additional_metadata_to_kv(additional_metadata),
+              workflow_ids: workflow_ids,
+              worker_id: worker_id,
+              parent_task_external_id: parent_task_external_id,
+              triggering_event_external_id: triggering_event_external_id
+            }
+          )
+        end
+
+        # Hack for uniqueness
+        run_id_to_run = {}
+        responses.each do |record|
+          record.rows.each do |run|
+            run_id_to_run[run.metadata.id] = run
+          end
+        end
+
+        run_id_to_run.values.sort_by(&:created_at).reverse
+      end
+
+      # List task runs according to a set of filters
+      #
+      # @param since [Time, nil] The start time for filtering task runs
+      # @param only_tasks [Boolean] Whether to only list task runs
+      # @param offset [Integer, nil] The offset for pagination
+      # @param limit [Integer, nil] The maximum number of task runs to return
+      # @param statuses [Array<HatchetSdkRest::V1TaskStatus>, nil] The statuses to filter task runs by
+      # @param until_time [Time, nil] The end time for filtering task runs
+      # @param additional_metadata [Hash<String, String>, nil] Additional metadata to filter task runs by
+      # @param workflow_ids [Array<String>, nil] The workflow IDs to filter task runs by
+      # @param worker_id [String, nil] The worker ID to filter task runs by
+      # @param parent_task_external_id [String, nil] The parent task external ID to filter task runs by
+      # @param triggering_event_external_id [String, nil] The event id that triggered the task run
+      # @return [HatchetSdkRest::V1TaskSummaryList] A list of task runs matching the specified filters
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def list(
+        since: nil,
+        only_tasks: false,
+        offset: nil,
+        limit: nil,
+        statuses: nil,
+        until_time: nil,
+        additional_metadata: nil,
+        workflow_ids: nil,
+        worker_id: nil,
+        parent_task_external_id: nil,
+        triggering_event_external_id: nil
+      )
+        since = since || (Time.now - DEFAULT_SINCE_DAYS * 24 * 60 * 60)
+        until_time = until_time || Time.now
+
+        if (until_time - since) / (24 * 60 * 60) >= LARGE_DATE_RANGE_WARNING_DAYS
+          warn "Listing runs with a date range longer than #{LARGE_DATE_RANGE_WARNING_DAYS} days may result in performance issues. " +
+               "Consider using `list_with_pagination` instead."
+        end
+
+        @workflow_runs_api.v1_workflow_run_list(
+          @config.tenant_id,
+          since.utc.iso8601,
+          only_tasks,
+          {
+            offset: offset,
+            limit: limit,
+            statuses: statuses,
+            until: until_time.utc.iso8601,
+            additional_metadata: maybe_additional_metadata_to_kv(additional_metadata),
+            workflow_ids: workflow_ids,
+            worker_id: worker_id,
+            parent_task_external_id: parent_task_external_id,
+            triggering_event_external_id: triggering_event_external_id
+          }
+        )
+      end
+
+      # Creates a new workflow run in the Hatchet system
+      #
+      # This method triggers a new workflow or task run for the specified workflow using the
+      # provided input data. The workflow run will be queued according to the
+      # workflow definition on an available worker.
+      #
+      # IMPORTANT: It's preferable to use `Workflow.run` (and similar) to trigger workflows if possible. 
+      # This method is intended to be an escape hatch.
+      #
+      # @param name [String] The name of the workflow to trigger
+      # @param input [Hash] The input data for the workflow run
+      # @param additional_metadata [Hash, nil] Additional metadata associated with the workflow run
+      # @param priority [Integer, nil] The priority of the workflow run
+      # @return [HatchetSdkRest::V1WorkflowRunDetails] The details of the triggered workflow run
+      # @raise [ArgumentError] If the workflow_name or input parameters are nil or invalid
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      # @example Creating a workflow run
+      #   response = runs.create(
+      #     name: "simple-workflow",
+      #     input: { user_id: 123, action: "process_data" },
+      #     additional_metadata: { source: "api", priority: "high" }
+      #   )
+      def create(name:, input:, additional_metadata: nil, priority: nil)
+        trigger_request = HatchetSdkRest::V1TriggerWorkflowRunRequest.new(
+          workflow_name: @config.apply_namespace(name),
+          input: input,
+          additional_metadata: additional_metadata,
+          priority: priority
+        )
+
+        run = @workflow_runs_api.v1_workflow_run_create(@config.tenant_id, trigger_request)
+        run.run
+      end
+
+      # Replay a task or workflow run
+      #
+      # @param run_id [String] The external ID of the task or workflow run to replay
+      # @return [void]
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def replay(run_id)
+        bulk_replay(BulkCancelReplayOpts.new(ids: [run_id]))
+      end
+
+      # Replay task or workflow runs in bulk, according to a set of filters
+      #
+      # @param opts [BulkCancelReplayOpts] Options for bulk replay, including filters and IDs
+      # @return [void]
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def bulk_replay(opts)
+        @task_api.v1_task_replay(
+          @config.tenant_id,
+          opts.to_replay_request
+        )
+      end
+
+      # Cancel a task or workflow run
+      #
+      # @param run_id [String] The external ID of the task or workflow run to cancel
+      # @return [void]
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def cancel(run_id)
+        bulk_cancel(BulkCancelReplayOpts.new(ids: [run_id]))
+      end
+
+      # Cancel task or workflow runs in bulk, according to a set of filters
+      #
+      # @param opts [BulkCancelReplayOpts] Options for bulk cancel, including filters and IDs
+      # @return [void]
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def bulk_cancel(opts)
+        @task_api.v1_task_cancel(
+          @config.tenant_id,
+          opts.to_cancel_request
+        )
+      end
+
+      # Get the result of a workflow run by its external ID
+      #
+      # @param run_id [String] The external ID of the workflow run to retrieve the result for
+      # @return [Hash] The result of the workflow run
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      def get_result(run_id)
+        details = get(run_id)
+        details.run.output
+      end
+
+      # Poll for workflow run completion with configurable interval and timeout
+      #
+      # This method repeatedly calls `get` until the workflow run reaches a terminal state
+      # (succeeded, failed, or cancelled) or the timeout is reached.
+      #
+      # @param workflow_run_id [String] The ID of the workflow run to poll
+      # @param interval [Numeric] The polling interval in seconds (default: 1.0)
+      # @param timeout [Numeric, nil] The maximum time to poll in seconds (default: no timeout)
+      # @return [HatchetSdkRest::V1WorkflowRunDetails] The final workflow run details
+      # @raise [Timeout::Error] If the timeout is reached before completion
+      # @raise [Hatchet::Error] If the API request fails or returns an error
+      # @example Poll with default settings (1s interval, no timeout)
+      #   result = runs.poll("workflow-run-123")
+      # @example Poll with custom interval and timeout
+      #   result = runs.poll("workflow-run-123", interval: 2.0, timeout: 30.0)
+      # @since 0.1.0
+      def poll(workflow_run_id, interval: 1.0, timeout: nil)
+        start_time = Time.now
+        
+        loop do
+          puts "Polling for completion of run #{workflow_run_id}"
+          details = get(workflow_run_id)
+          status = details.run.status
+          
+          # Check if workflow run has reached a terminal state
+          puts "Run status: #{status}"
+          if terminal_status?(status)
+            return details
+          end
+          
+          # Check timeout
+          if timeout && (Time.now - start_time) >= timeout
+            raise Timeout::Error, "Polling timed out after #{timeout} seconds"
+          end
+          
+          sleep(interval)
+        end
+      end
+
+      private
+
+      # Check if a workflow run status is terminal (completed)
+      #
+      # @param status [String] The workflow run status
+      # @return [Boolean] True if the status is terminal (succeeded, failed, or cancelled)
+      def terminal_status?(status)
+        case status
+        when HatchetSdkRest::WorkflowRunStatus::SUCCEEDED,
+             HatchetSdkRest::WorkflowRunStatus::FAILED,
+             HatchetSdkRest::WorkflowRunStatus::CANCELLED,
+             HatchetSdkRest::V1TaskStatus::COMPLETED,
+             HatchetSdkRest::V1TaskStatus::CANCELLED,
+             HatchetSdkRest::V1TaskStatus::FAILED
+          true
+        else
+          false
+        end
+      end
+
+      # Partition a date range into daily chunks to avoid API limits
+      #
+      # @param since [Time] Start time
+      # @param until_time [Time] End time
+      # @return [Array<Array<Time, Time>>] Array of [start_time, end_time] pairs
+      def partition_date_range(since:, until_time:)
+        ranges = []
+        current = since
+        
+        while current < until_time
+          next_day = [current + 24 * 60 * 60, until_time].min
+          ranges << [current, next_day]
+          current = next_day
+        end
+        
+        ranges
+      end
+
+      # Convert additional metadata hash to key-value array format expected by API
+      #
+      # @param metadata [Hash<String, String>, nil] Metadata hash
+      # @return [Array<Hash>, nil] Array of {key: string, value: string} objects
+      def maybe_additional_metadata_to_kv(metadata)
+        return nil unless metadata
+        metadata.map { |k, v| { key: k.to_s, value: v.to_s } }
+      end
+    end
+  end
+end

data/lib/hatchet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hatchet
-  VERSION = "0.0.1"
+  VERSION = "0.1.0-alpha"
 end

data/lib/hatchet-sdk.rb

@@ -3,6 +3,9 @@
 
 require_relative "hatchet/version"
 require_relative "hatchet/config"
+require_relative "hatchet/clients"
+require_relative "hatchet/features/events"
+require_relative "hatchet/features/runs"
 
 # Ruby SDK for Hatchet workflow engine
 #
@@ -61,5 +64,23 @@ module Hatchet
     def initialize(**options)
       @config = Config.new(**options)
     end
+
+    def rest_client
+        @rest_client ||= Hatchet::Clients.rest_client(@config)
+    end
+
+    # Feature Client for interacting with Hatchet events
+    # @return [Hatchet::Features::Events] The events client for interacting with Hatchet events
+    def events
+      # @type [Hatchet::Features::Events]
+      @events ||= Hatchet::Features::Events.new(rest_client, @config)
+    end
+
+    # Feature Client for interacting with Hatchet workflow runs
+    # @return [Hatchet::Features::Runs] The runs client for interacting with Hatchet workflow runs
+    def runs
+      # @type [Hatchet::Features::Runs]
+      @runs ||= Hatchet::Features::Runs.new(rest_client, @config)
+    end
   end
 end

data/scripts/generate.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+
+# Ruby SDK REST API Client Generation Script
+# Similar to the Python SDK's generate.sh
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+OPENAPI_SPEC="$PROJECT_ROOT/../../../../bin/oas/openapi.yaml"
+OUTPUT_DIR="$PROJECT_ROOT/lib/hatchet/clients/rest"
+CONFIG_FILE="$PROJECT_ROOT/config/openapi_generator_config.json"
+
+echo -e "${BLUE}🚀 Starting Ruby REST API Client Generation${NC}"
+echo "Project Root: $PROJECT_ROOT"
+
+# Function to check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Function to install OpenAPI Generator CLI
+install_openapi_generator() {
+    echo -e "${YELLOW}📦 Installing OpenAPI Generator CLI...${NC}"
+    
+    if command_exists npm; then
+        npm install -g @openapitools/openapi-generator-cli@7.13.0
+        echo -e "${GREEN}✅ OpenAPI Generator CLI installed${NC}"
+    else
+        echo -e "${RED}❌ npm not found. Please install Node.js and npm first.${NC}"
+        exit 1
+    fi
+}
+
+# Function to validate OpenAPI spec
+validate_spec() {
+    echo -e "${BLUE}🔍 Validating OpenAPI specification...${NC}"
+    
+    if [ ! -f "$OPENAPI_SPEC" ]; then
+        echo -e "${RED}❌ OpenAPI spec not found at: $OPENAPI_SPEC${NC}"
+        exit 1
+    fi
+    
+    openapi-generator-cli validate -i "$OPENAPI_SPEC"
+    echo -e "${GREEN}✅ OpenAPI specification is valid${NC}"
+}
+
+# Function to generate the REST client
+generate_client() {
+    echo -e "${BLUE}🏗️  Generating Ruby REST client...${NC}"
+    
+    # Create output directory
+    mkdir -p "$OUTPUT_DIR"
+    
+    # Additional properties for Ruby generation
+    ADDITIONAL_PROPS="gemName=hatchet-sdk-rest,moduleName=Hatchet::Clients::Rest,gemVersion=0.0.1,gemDescription=Ruby REST client for Hatchet API,gemAuthor=Hatchet Team,gemHomepage=https://github.com/hatchet-dev/hatchet,gemLicense=MIT,library=faraday,httpLibrary=faraday"
+    
+    # Generate the client
+    openapi-generator-cli generate \
+        -i "$OPENAPI_SPEC" \
+        -g ruby \
+        -o "$OUTPUT_DIR" \
+        -c "$CONFIG_FILE" \
+        --skip-validate-spec \
+        --global-property apiTests=false,modelTests=false,apiDocs=true,modelDocs=true \
+        --additional-properties "$ADDITIONAL_PROPS"
+    
+    echo -e "${GREEN}✅ Ruby REST client generated${NC}"
+}
+
+# Function to apply custom patches
+apply_patches() {
+    echo -e "${BLUE}🔧 Applying custom patches...${NC}"
+    
+    echo -e "${GREEN}✅ Custom patches applied${NC}"
+}
+
+# Function to update dependencies
+update_dependencies() {
+    echo -e "${BLUE}📦 Updating Ruby dependencies...${NC}"
+    
+    cd "$PROJECT_ROOT"
+    
+    # Add required gems to Gemfile if not present
+    if ! grep -q "gem ['\"]faraday['\"]" Gemfile 2>/dev/null; then
+        echo "gem 'faraday', '~> 2.0'" >> Gemfile
+    fi
+    
+    if ! grep -q "gem ['\"]faraday-multipart['\"]" Gemfile 2>/dev/null; then
+        echo "gem 'faraday-multipart'" >> Gemfile
+    fi
+    
+    # Install/update dependencies
+    bundle install
+    
+    echo -e "${GREEN}✅ Dependencies updated${NC}"
+}
+
+# Function to run tests on generated code
+run_tests() {
+    echo -e "${BLUE}🧪 Running tests...${NC}"
+    
+    cd "$PROJECT_ROOT"
+    
+    # Run RSpec tests
+    bundle exec rspec
+    
+    # Run RuboCop
+    bundle exec rubocop --auto-correct
+    
+    echo -e "${GREEN}✅ Tests completed${NC}"
+}
+
+# Main execution
+main() {
+    echo -e "${BLUE}Starting Ruby REST API generation process...${NC}"
+    
+    # Check if OpenAPI Generator CLI is installed
+    if ! command_exists openapi-generator-cli; then
+        echo -e "${YELLOW}OpenAPI Generator CLI not found${NC}"
+        install_openapi_generator
+    else
+        echo -e "${GREEN}✅ OpenAPI Generator CLI found${NC}"
+    fi
+    
+    # Validate the OpenAPI specification
+    validate_spec
+    
+    # Generate the REST client
+    generate_client
+    
+    # Apply custom patches
+    apply_patches
+    
+    # Update dependencies
+    update_dependencies
+    
+    # Run tests (optional, can be disabled with --skip-tests)
+    if [[ "$*" != *"--skip-tests"* ]]; then
+        run_tests
+    fi
+    
+    echo -e "${GREEN}🎉 Ruby REST API client generation completed successfully!${NC}"
+    echo -e "${BLUE}Generated files are in: $OUTPUT_DIR${NC}"
+}
+
+# Handle command line arguments
+case "$1" in
+    --help|-h)
+        echo "Usage: $0 [OPTIONS]"
+        echo "Options:"
+        echo "  --skip-tests    Skip running tests after generation"
+        echo "  --help, -h      Show this help message"
+        exit 0
+        ;;
+    *)
+        main "$@"
+        ;;
+esac