Module: StandardId::Events

Includes:
Definitions
Defined in:
lib/standard_id/events.rb,
lib/standard_id/events/event.rb,
lib/standard_id/events/definitions.rb,
lib/standard_id/events/subscribers/base.rb,
lib/standard_id/events/subscribers/logging_subscriber.rb,
lib/standard_id/events/subscribers/account_status_subscriber.rb,
lib/standard_id/events/subscribers/account_locking_subscriber.rb,
lib/standard_id/events/subscribers/passwordless_delivery_subscriber.rb

Defined Under Namespace

Modules: Definitions, Subscribers Classes: Event

Constant Summary collapse

NAMESPACE =

Event namespace prefix for all StandardId events

"standard_id"

Constants included from Definitions

Definitions::ACCOUNT_ACTIVATED, Definitions::ACCOUNT_CREATED, Definitions::ACCOUNT_CREATING, Definitions::ACCOUNT_DEACTIVATED, Definitions::ACCOUNT_EVENTS, Definitions::ACCOUNT_LOCKED, Definitions::ACCOUNT_STATUS_CHANGED, Definitions::ACCOUNT_UNLOCKED, Definitions::ACCOUNT_VERIFIED, Definitions::ALL_EVENTS, Definitions::AUTHENTICATION_ATTEMPT_STARTED, Definitions::AUTHENTICATION_EVENTS, Definitions::AUTHENTICATION_FAILED, Definitions::AUTHENTICATION_SUCCEEDED, Definitions::CREDENTIAL_CLIENT_SECRET_CREATED, Definitions::CREDENTIAL_CLIENT_SECRET_REVOKED, Definitions::CREDENTIAL_CLIENT_SECRET_ROTATED, Definitions::CREDENTIAL_EVENTS, Definitions::CREDENTIAL_PASSWORD_CHANGED, Definitions::CREDENTIAL_PASSWORD_CREATED, Definitions::CREDENTIAL_PASSWORD_RESET_COMPLETED, Definitions::CREDENTIAL_PASSWORD_RESET_INITIATED, Definitions::IDENTIFIER_CREATED, Definitions::IDENTIFIER_EVENTS, Definitions::IDENTIFIER_LINKED, Definitions::IDENTIFIER_VERIFICATION_FAILED, Definitions::IDENTIFIER_VERIFICATION_STARTED, Definitions::IDENTIFIER_VERIFICATION_SUCCEEDED, Definitions::OAUTH_AUTHORIZATION_DENIED, Definitions::OAUTH_AUTHORIZATION_GRANTED, Definitions::OAUTH_AUTHORIZATION_REQUESTED, Definitions::OAUTH_CODE_CONSUMED, Definitions::OAUTH_EVENTS, Definitions::OAUTH_REFRESH_TOKEN_REUSE_DETECTED, Definitions::OAUTH_TOKEN_ISSUED, Definitions::OAUTH_TOKEN_ISSUING, Definitions::OAUTH_TOKEN_REFRESHED, Definitions::OAUTH_TOKEN_REVOKED, Definitions::OTP_VALIDATED, Definitions::OTP_VALIDATION_FAILED, Definitions::PASSWORDLESS_ACCOUNT_CREATED, Definitions::PASSWORDLESS_CODE_FAILED, Definitions::PASSWORDLESS_CODE_GENERATED, Definitions::PASSWORDLESS_CODE_REQUESTED, Definitions::PASSWORDLESS_CODE_SENT, Definitions::PASSWORDLESS_CODE_VERIFIED, Definitions::PASSWORDLESS_EVENTS, Definitions::PASSWORD_VALIDATED, Definitions::PASSWORD_VALIDATION_FAILED, Definitions::SECURITY_EVENTS, Definitions::SESSION_CREATED, Definitions::SESSION_CREATING, Definitions::SESSION_EVENTS, Definitions::SESSION_EXPIRED, Definitions::SESSION_REFRESHED, Definitions::SESSION_REVOKED, Definitions::SESSION_VALIDATED, Definitions::SESSION_VALIDATING, Definitions::SOCIAL_ACCOUNT_CREATED, Definitions::SOCIAL_ACCOUNT_LINKED, Definitions::SOCIAL_AUTH_COMPLETED, Definitions::SOCIAL_AUTH_STARTED, Definitions::SOCIAL_CALLBACK_RECEIVED, Definitions::SOCIAL_EVENTS, Definitions::SOCIAL_LINK_BLOCKED, Definitions::SOCIAL_USER_INFO_FETCHED

Class Method Summary collapse

Class Method Details

.namespaced_event_name(event_name) ⇒ String

Get the full namespaced event name

Parameters:

  • event_name (String, Symbol) —

    The short event name

Returns:

  • (String) —

    The full namespaced event name



97
98
99
100
101
 
# File 'lib/standard_id/events.rb', line 97

def namespaced_event_name(event_name)
  return event_name.to_s if event_name.to_s.start_with?("#{NAMESPACE}.")

  "#{NAMESPACE}.#{event_name}"
end

.publish(event_name, payload = {}) {|Hash| ... } ⇒ void

This method returns an undefined value.

Publish an event with the given name and payload

Examples:

Simple publish

StandardId::Events.publish(:authentication_succeeded, account: user)

With block for lazy payload

StandardId::Events.publish(:authentication_succeeded) do
  { account: expensive_lookup, duration_ms: calculate_duration }
end

Parameters:

  • event_name (String, Symbol) —

    The event name (use constants from Definitions)

  • payload (Hash) (defaults to: {}) —

    The event payload data

Yields:

  • (Hash) —

    Optional block that receives the payload, useful for lazy evaluation



25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/standard_id/events.rb', line 25

def publish(event_name, payload = {}, &block)
  event_payload = block ? block.call.merge(payload) : payload
  full_event_name = namespaced_event_name(event_name)

  # Add standard metadata to all events
  enriched_payload = enrich_payload(event_payload, event_name)

  ActiveSupport::Notifications.instrument(full_event_name, enriched_payload)
rescue ActiveSupport::Notifications::InstrumentationSubscriberError => e
  # Re-raise the first exception only (stop at first failure)
  # This prevents confusing "multiple exceptions" messages when
  # multiple guards (e.g., AccountStatus + AccountLocking) both fail
  raise e.exceptions.first if e.exceptions.any?
end

.subscribe(*event_names) {|StandardId::Events::Event| ... } ⇒ ActiveSupport::Notifications::Fanout::Subscribers::Evented, Array

Subscribe to an event with a block or callable

Examples:

Block subscription

StandardId::Events.subscribe(:authentication_succeeded) do |event|
  puts "Login from #{event.payload[:ip_address]}"
end

Multiple events subscription

StandardId::Events.subscribe(:session_creating, :session_validating) do |event|
  (event)
end

Pattern subscription (subscribe to all authentication events)

StandardId::Events.subscribe(/authentication/) do |event|
  audit_log(event)
end

Parameters:

  • event_names (String, Symbol, Array<String, Symbol>) —

    The event name(s) to subscribe to

Yields:

Returns:

  • (ActiveSupport::Notifications::Fanout::Subscribers::Evented, Array) —

    The subscription(s)



61
62
63
64
65
66
67
68
69
 
# File 'lib/standard_id/events.rb', line 61

def subscribe(*event_names, &block)
  event_names = event_names.flatten

  if event_names.size == 1
    subscribe_single(event_names.first, &block)
  else
    event_names.map { |event_name| subscribe_single(event_name, &block) }
  end
end

.subscribe_to_pattern(pattern) {|StandardId::Events::Event| ... } ⇒ ActiveSupport::Notifications::Fanout::Subscribers::Evented

Subscribe to an event pattern using a regex

Parameters:

  • pattern (Regexp) —

    The pattern to match event names

Yields:

Returns:

  • (ActiveSupport::Notifications::Fanout::Subscribers::Evented) —

    The subscription



77
78
79
 
# File 'lib/standard_id/events.rb', line 77

def subscribe_to_pattern(pattern, &block)
  subscribe_single(pattern, &block)
end

.unsubscribe(*subscribers) ⇒ void

This method returns an undefined value.

Unsubscribe from events

Parameters:

  • subscribers (Object, Array<Object>) —

    The subscriber(s) returned from subscribe()



86
87
88
89
90
 
# File 'lib/standard_id/events.rb', line 86

def unsubscribe(*subscribers)
  subscribers.flatten.each do |subscriber|
    ActiveSupport::Notifications.unsubscribe(subscriber)
  end
end