Class: Hatchet::Features::Events

Inherits:
Object
  • Object
show all
Defined in:
lib/hatchet/features/events.rb

Overview

Events client for interacting with Hatchet event management API

This class provides a high-level interface for creating and managing events in the Hatchet system. It uses gRPC for event creation (push/bulk_push) and the REST API for read operations (list, get, etc.).

Examples:

Creating an event

response = events.push(
  key: "user-login",
  data: { user_id: 123, action: "login" },
  additional_metadata: { ip_address: "192.168.1.1" }
)

Since:

  • 0.1.0

Constant Summary collapse

CreateEventRequest =

Re-export commonly used event classes for convenience

Since:

  • 0.1.0

::HatchetSdkRest::CreateEventRequest
BulkCreateEventRequest =

Since:

  • 0.1.0

::HatchetSdkRest::BulkCreateEventRequest
EventList =

Since:

  • 0.1.0

::HatchetSdkRest::V1EventList

Instance Method Summary collapse

Constructor Details

#initialize(rest_client, event_grpc, config) ⇒ void

Initializes a new Events client instance

Parameters:

  • rest_client (Object) —

    The configured REST client for API communication

  • event_grpc (Hatchet::Clients::Grpc::EventClient) —

    The gRPC event client for push operations

  • config (Hatchet::Config) —

    The Hatchet configuration containing tenant_id and other settings

Since:

  • 0.1.0



34
35
36
37
38
39
 
# File 'lib/hatchet/features/events.rb', line 34

def initialize(rest_client, event_grpc, config)
  @rest_client = rest_client
  @event_grpc = event_grpc
  @config = config
  @event_api = HatchetSdkRest::EventApi.new(rest_client)
end

Instance Method Details

#bulk_push(events, namespace: nil) ⇒ Object

Create events in bulk

Examples:

Bulk create events

events_data = [
  { key: "user-signup", data: { user_id: 1 } },
  { key: "user-login", data: { user_id: 1 }, priority: 1 }
]
response = events.bulk_push(events_data)

Parameters:

  • events (Array<Hash>) —

    Array of event hashes, each containing :key, :data, and optionally :additional_metadata and :priority

  • namespace (String, nil) (defaults to: nil) —

    Override namespace for all events

Returns:

  • (Object) —

    The gRPC response containing the created events

Raises:

Since:

  • 0.1.0



110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/hatchet/features/events.rb', line 110

def bulk_push(events, namespace: nil)
  grpc_events = events.map do |event|
    {
      key: event[:key],
      payload: event[:data] || {},
      additional_metadata: event[:additional_metadata],
      priority: event[:priority],
    }
  end

  @event_grpc.bulk_push(grpc_events, namespace: namespace)
end

#cancel(event_ids: nil, keys: nil, since: nil, until_time: nil) ⇒ Object

Cancel events matching the given criteria

Parameters:

  • event_ids (Array<String>, nil) (defaults to: nil) —

    Specific event IDs to cancel

  • keys (Array<String>, nil) (defaults to: nil) —

    Event keys to cancel

  • since (Time, nil) (defaults to: nil) —

    Cancel events after this time

  • until_time (Time, nil) (defaults to: nil) —

    Cancel events before this time

Returns:

  • (Object) —

    The cancellation response

Raises:

Since:

  • 0.1.0



206
207
208
209
210
211
212
 
# File 'lib/hatchet/features/events.rb', line 206

def cancel(event_ids: nil, keys: nil, since: nil, until_time: nil)
  cancel_request = HatchetSdkRest::CancelEventRequest.new(
    event_ids: event_ids,
  )

  @event_api.event_update_cancel(@config.tenant_id, cancel_request)
end

#create(key:, data:, additional_metadata: nil, priority: nil, scope: nil, namespace: nil) ⇒ Object

Creates a new event in the Hatchet system

This method sends an event creation request via gRPC. The event will be processed and made available for workflow triggers and event-driven automation.

Examples:

Creating a simple event

response = events.create(
  key: "user-login",
  data: { user_id: 123, action: "login" },
  additional_metadata: { ip_address: "192.168.1.1" }
)

Parameters:

  • key (String) —

    The event key/name

  • data (Hash) —

    The event payload data

  • additional_metadata (Hash, nil) (defaults to: nil) —

    Additional metadata for the event

  • priority (Integer, nil) (defaults to: nil) —

    Event priority

  • scope (String, nil) (defaults to: nil) —

    The scope for event filtering

  • namespace (String, nil) (defaults to: nil) —

    Override namespace for this event

Returns:

  • (Object) —

    The gRPC response containing the created event details

Raises:

  • (ArgumentError) —

    If required parameters are missing

  • (Hatchet::Error) —

    If the API request fails or returns an error

Since:

  • 0.1.0



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/hatchet/features/events.rb', line 62

def create(key:, data:, additional_metadata: nil, priority: nil, scope: nil, namespace: nil)
  @event_grpc.push(
    key: key,
    payload: data,
    additional_metadata: additional_metadata,
    priority: priority,
    scope: scope,
    namespace: namespace,
  )
end

#get(event_id) ⇒ Object

Get a specific event by ID

Parameters:

  • event_id (String) —

    The event ID

Returns:

  • (Object) —

    The event details

Raises:

Since:

  • 0.1.0



177
178
179
 
# File 'lib/hatchet/features/events.rb', line 177

def get(event_id)
  @event_api.v1_event_get(@config.tenant_id, event_id)
end

#get_data(event_id) ⇒ Object

Get event data for a specific event

Parameters:

  • event_id (String) —

    The event ID

Returns:

  • (Object) —

    The event data

Raises:

Since:

  • 0.1.0



186
187
188
 
# File 'lib/hatchet/features/events.rb', line 186

def get_data(event_id)
  @event_api.event_data_get_with_tenant(event_id, @config.tenant_id)
end

#list(offset: nil, limit: nil, keys: nil, since: nil, until_time: nil, workflow_ids: nil, workflow_run_statuses: nil, event_ids: nil, additional_metadata: nil, scopes: nil) ⇒ HatchetSdkRest::V1EventList

List events with filtering options

Examples:

List recent events

events = events_client.list(
  limit: 10,
  since: Time.now - 24 * 60 * 60,
  keys: ["user-signup", "user-login"]
)

Parameters:

  • offset (Integer, nil) (defaults to: nil) —

    Pagination offset

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of events to return

  • keys (Array<String>, nil) (defaults to: nil) —

    Filter by event keys

  • since (Time, nil) (defaults to: nil) —

    Filter events after this time

  • until_time (Time, nil) (defaults to: nil) —

    Filter events before this time

  • workflow_ids (Array<String>, nil) (defaults to: nil) —

    Filter by workflow IDs

  • workflow_run_statuses (Array<String>, nil) (defaults to: nil) —

    Filter by workflow run statuses

  • event_ids (Array<String>, nil) (defaults to: nil) —

    Filter by specific event IDs

  • additional_metadata (Hash<String, String>, nil) (defaults to: nil) —

    Filter by additional metadata

  • scopes (Array<String>, nil) (defaults to: nil) —

    Filter by event scopes

Returns:

Raises:

Since:

  • 0.1.0



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/hatchet/features/events.rb', line 143

def list(
  offset: nil,
  limit: nil,
  keys: nil,
  since: nil,
  until_time: nil,
  workflow_ids: nil,
  workflow_run_statuses: nil,
  event_ids: nil,
  additional_metadata: nil,
  scopes: nil
)
  @event_api.v1_event_list(
    @config.tenant_id,
    {
      offset: offset,
      limit: limit,
      keys: keys,
      since: since&.utc&.iso8601,
      _until: until_time&.utc&.iso8601,
      workflow_ids: workflow_ids,
      workflow_run_statuses: workflow_run_statuses,
      event_ids: event_ids,
      additional_metadata: maybe_additional_metadata_to_kv(additional_metadata),
      scopes: scopes,
    },
  )
end

#list_keys ⇒ Object

List available event keys for the tenant

Returns:

  • (Object) —

    List of available event keys

Raises:

Since:

  • 0.1.0



194
195
196
 
# File 'lib/hatchet/features/events.rb', line 194

def list_keys
  @event_api.v1_event_key_list(@config.tenant_id)
end

#push(event_key, payload, additional_metadata: nil, namespace: nil, priority: nil) ⇒ Object

Push a single event to Hatchet

Examples:

Push a simple event

response = events.push(
  "user-signup",
  { user_id: 456, email: "user@example.com" },
  additional_metadata: { source: "web" }
)

Parameters:

  • event_key (String) —

    The event key/name

  • payload (Hash) —

    The event payload data

  • additional_metadata (Hash, nil) (defaults to: nil) —

    Additional metadata for the event

  • namespace (String, nil) (defaults to: nil) —

    Override namespace for this event

  • priority (Integer, nil) (defaults to: nil) —

    Event priority

Returns:

  • (Object) —

    The gRPC response containing the created event details

Raises:

Since:

  • 0.1.0



88
89
90
91
92
93
94
95
96
 
# File 'lib/hatchet/features/events.rb', line 88

def push(event_key, payload, additional_metadata: nil, namespace: nil, priority: nil)
  create(
    key: event_key,
    data: payload,
    additional_metadata: additional_metadata,
    priority: priority,
    namespace: namespace,
  )
end

#replay(event_ids: nil, keys: nil, since: nil, until_time: nil) ⇒ Object

Replay events matching the given criteria

Parameters:

  • event_ids (Array<String>, nil) (defaults to: nil) —

    Specific event IDs to replay

  • keys (Array<String>, nil) (defaults to: nil) —

    Event keys to replay

  • since (Time, nil) (defaults to: nil) —

    Replay events after this time

  • until_time (Time, nil) (defaults to: nil) —

    Replay events before this time

Returns:

  • (Object) —

    The replay response

Raises:

Since:

  • 0.1.0



222
223
224
225
226
227
228
 
# File 'lib/hatchet/features/events.rb', line 222

def replay(event_ids: nil, keys: nil, since: nil, until_time: nil)
  replay_request = HatchetSdkRest::ReplayEventRequest.new(
    event_ids: event_ids,
  )

  @event_api.event_update_replay(@config.tenant_id, replay_request)
end