Class: Botiasloop::Channels::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/botiasloop/channels/base.rb

Direct Known Subclasses

CLI, Telegram

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Base

Initialize the channel

Raises:

  • (Error) —

    If required configuration is missing



40
41
42
 
# File 'lib/botiasloop/channels/base.rb', line 40

def initialize
  validate_required_config!
end

Class Attribute Details

.channel_identifier=(value) ⇒ Object (writeonly)

Sets the attribute channel_identifier

Parameters:

  • value —

    the value to set the attribute channel_identifier to.



10
11
12
 
# File 'lib/botiasloop/channels/base.rb', line 10

def channel_identifier=(value)
  @channel_identifier = value
end

Class Method Details

.channel_name(name = nil) ⇒ Symbol Also known as: channel_identifier

Get or set the channel identifier

Parameters:

  • name (Symbol) (defaults to: nil) —

    Channel identifier (e.g., :telegram)

Returns:

  • (Symbol) —

    The channel identifier



15
16
17
18
 
# File 'lib/botiasloop/channels/base.rb', line 15

def channel_name(name = nil)
  @channel_identifier = name if name
  @channel_identifier
end

.required_config_keys ⇒ Array<Symbol>

Get required configuration keys

Returns:

  • (Array<Symbol>) —

    Required configuration keys



32
33
34
 
# File 'lib/botiasloop/channels/base.rb', line 32

def required_config_keys
  @required_config_keys ||= []
end

.requires_config(*keys) ⇒ Object

Declare required configuration keys

Parameters:

  • keys (Array<Symbol>) —

    Required configuration keys



24
25
26
27
28
 
# File 'lib/botiasloop/channels/base.rb', line 24

def requires_config(*keys)
  @required_config_keys ||= []
  @required_config_keys.concat(keys) if keys.any?
  @required_config_keys
end

Instance Method Details

#after_process(source_id, user_id, response, raw_message) ⇒ Object

Hook called after processing a message Override in subclasses for custom post-processing (e.g., logging)

Parameters:

  • source_id (String) —

    Source identifier

  • user_id (String) —

    User ID

  • response (String) —

    Response content

  • raw_message (Object) —

    Raw message object



165
166
167
 
# File 'lib/botiasloop/channels/base.rb', line 165

def after_process(source_id, user_id, response, raw_message)
  # No-op by default
end

#authorized?(_source_id) ⇒ Boolean

Check if a source is authorized to use this channel

Parameters:

  • source_id (String) —

    Source identifier to check

Returns:

  • (Boolean) —

    False by default (secure default)



195
196
197
 
# File 'lib/botiasloop/channels/base.rb', line 195

def authorized?(_source_id)
  false
end

#before_process(source_id, user_id, content, raw_message) ⇒ Object

Hook called before processing a message Override in subclasses for custom pre-processing (e.g., logging)

Parameters:

  • source_id (String) —

    Source identifier

  • user_id (String) —

    User ID

  • content (String) —

    Message content

  • raw_message (Object) —

    Raw message object



154
155
156
 
# File 'lib/botiasloop/channels/base.rb', line 154

def before_process(source_id, user_id, content, raw_message)
  # No-op by default
end

#channel_config ⇒ Hash

Get channel-specific configuration Override in subclasses for custom config access

Returns:

  • (Hash) —

    Channel configuration hash



48
49
50
 
# File 'lib/botiasloop/channels/base.rb', line 48

def channel_config
  Config.instance.channels[self.class.channel_identifier.to_s] || {}
end

#channel_type ⇒ String

Get the channel type string (e.g., “telegram”, “cli”) Override in subclasses if needed

Returns:

  • (String) —

    Channel type string



56
57
58
 
# File 'lib/botiasloop/channels/base.rb', line 56

def channel_type
  self.class.channel_identifier.to_s
end

#chat_for(source_id, user_identifier: nil) ⇒ Chat

Get or create a chat for a source

Parameters:

  • source_id (String) —

    Source identifier

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

    Optional user identifier (e.g., username)

Returns:

  • (Chat) —

    Chat instance



204
205
206
 
# File 'lib/botiasloop/channels/base.rb', line 204

def chat_for(source_id, user_identifier: nil)
  Chat.find_or_create(channel_type, source_id, user_identifier: user_identifier)
end

#deliver_message(source_id, formatted_content) ⇒ Object

Deliver a formatted message to a source

Parameters:

  • source_id (String) —

    Source identifier

  • formatted_content (String) —

    Formatted message content

Raises:

  • (NotImplementedError) —

    Subclass must implement



230
231
232
 
# File 'lib/botiasloop/channels/base.rb', line 230

def deliver_message(source_id, formatted_content)
  raise NotImplementedError, "Subclass must implement #deliver_message"
end

#extract_content(raw_message) ⇒ String

Extract content from raw message. Subclasses must implement.

Parameters:

  • raw_message (Object) —

    Raw message object

Returns:

  • (String) —

    Extracted message content

Raises:

  • (NotImplementedError) —

    Subclass must implement



133
134
135
 
# File 'lib/botiasloop/channels/base.rb', line 133

def extract_content(raw_message)
  raise NotImplementedError, "Subclass must implement #extract_content"
end

#extract_user_id(source_id, _raw_message) ⇒ String

Extract user ID from raw message for authorization Override in subclasses if user ID differs from source_id

Parameters:

  • source_id (String) —

    Source identifier

  • raw_message (Object) —

    Raw message object

Returns:

  • (String) —

    User ID for authorization



143
144
145
 
# File 'lib/botiasloop/channels/base.rb', line 143

def extract_user_id(source_id, _raw_message)
  source_id
end

#format_message(content) ⇒ String

Format a message for this channel

Parameters:

  • content (String) —

    Raw message content

Returns:

  • (String) —

    Formatted message



212
213
214
 
# File 'lib/botiasloop/channels/base.rb', line 212

def format_message(content)
  content
end

#handle_error(_source_id, _user_id, error, _raw_message) ⇒ Object

Handle errors during message processing Override in subclasses for custom error handling

Parameters:

  • source_id (String) —

    Source identifier

  • user_id (String) —

    User ID

  • error (Exception) —

    The error that occurred

  • raw_message (Object) —

    Raw message object



186
187
188
189
 
# File 'lib/botiasloop/channels/base.rb', line 186

def handle_error(_source_id, _user_id, error, _raw_message)
  Logger.error "[#{self.class.channel_identifier}] Error processing message: #{error.message}"
  raise error
end

#handle_unauthorized(source_id, user_id, _raw_message) ⇒ Object

Handle unauthorized access Override in subclasses for custom unauthorized handling

Parameters:

  • source_id (String) —

    Source identifier

  • user_id (String) —

    User ID that was denied

  • raw_message (Object) —

    Raw message object



175
176
177
 
# File 'lib/botiasloop/channels/base.rb', line 175

def handle_unauthorized(source_id, user_id, _raw_message)
  Logger.warn "[#{self.class.channel_identifier}] Unauthorized access from #{user_id} (source: #{source_id})"
end

#process_message(source_id, raw_message, _metadata = {}) ⇒ Object

Process an incoming message using template method pattern

Parameters:

  • source_id (String) —

    Unique identifier for the message source (e.g., chat_id, user_id)

  • raw_message (Object) —

    Raw message object (varies by channel)

  • metadata (Hash) —

    Additional metadata about the message



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/botiasloop/channels/base.rb', line 84

def process_message(source_id, raw_message, _metadata = {})
  # Hook: Extract content from raw message
  content = extract_content(raw_message)
  return if content.nil? || content.to_s.empty?

  # Hook: Extract user ID for authorization
  user_id = extract_user_id(source_id, raw_message)

  # Authorization check
  unless authorized?(user_id)
    handle_unauthorized(source_id, user_id, raw_message)
    return
  end

  # Hook: Pre-processing
  before_process(source_id, user_id, content, raw_message)

  # Core processing logic
  chat = chat_for(source_id, user_identifier: user_id)
  conversation = chat.current_conversation

  response = if Commands.command?(content)
    context = Commands::Context.new(
      conversation: conversation,
      chat: chat,
      channel: self,
      user_id: source_id
    )
    Commands.execute(content, context)
  else
    verbose_callback = proc do |verbose_message|
      send_message(source_id, verbose_message)
    end
    Agent.chat(content, conversation: conversation, verbose_callback: verbose_callback)
  end

  send_message(source_id, response)

  # Hook: Post-processing
  after_process(source_id, user_id, response, raw_message)
rescue => e
  handle_error(source_id, user_id, e, raw_message)
end

#running? ⇒ Boolean

Check if the channel is currently running

Returns:

  • (Boolean) —

    True if running

Raises:

  • (NotImplementedError) —

    Subclass must implement



75
76
77
 
# File 'lib/botiasloop/channels/base.rb', line 75

def running?
  raise NotImplementedError, "Subclass must implement #running?"
end

#send_message(source_id, message) ⇒ Object

Send a message to a source

Parameters:

  • source_id (String) —

    Source identifier

  • message (String) —

    Message content



220
221
222
223
 
# File 'lib/botiasloop/channels/base.rb', line 220

def send_message(source_id, message)
  formatted = format_message(message)
  deliver_message(source_id, formatted)
end

#start_listening ⇒ Object

Start the channel and begin listening for messages

Raises:

  • (NotImplementedError) —

    Subclass must implement



62
63
64
 
# File 'lib/botiasloop/channels/base.rb', line 62

def start_listening
  raise NotImplementedError, "Subclass must implement #start_listening"
end

#stop_listening ⇒ Object

Stop the channel and cleanup

Raises:

  • (NotImplementedError) —

    Subclass must implement



68
69
70
 
# File 'lib/botiasloop/channels/base.rb', line 68

def stop_listening
  raise NotImplementedError, "Subclass must implement #stop_listening"
end