chatrix 1.0.0.pre → 1.0.0

data/lib/chatrix/client.rb

@@ -0,0 +1,98 @@
+require 'chatrix/matrix'
+require 'chatrix/users'
+require 'chatrix/rooms'
+
+require 'wisper'
+
+module Chatrix
+  # A client wrapping the API in easy-to-use methods.
+  class Client
+    include Wisper::Publisher
+
+    # @!attribute [r] me
+    #   @return [User] The user associated with the access token.
+    attr_reader :me
+
+    # Initializes a new Client instance.
+    #
+    # Currently it requires a token, future versions will allow login
+    # with arbitrary details.
+    #
+    # @param token [String] The access token to use.
+    # @param id [String] The user ID of the token owner.
+    # @param homeserver [String,nil] Homeserver to connect to. If not set,
+    #   the default homeserver defined in Chatrix::Matrix will be used.
+    def initialize(token, id, homeserver: nil)
+      @matrix = Matrix.new token, homeserver
+
+      @users = Users.new
+      @rooms = Rooms.new @users, @matrix
+
+      @me = @users.send(:get_user, id)
+
+      @rooms.on(:added) do |room|
+        broadcast(:room_added, room)
+        room.timeline.on(:message) { |r, m| broadcast(:room_message, r, m) }
+      end
+    end
+
+    # Starts syncing against the homeserver.
+    #
+    # Launches a new thread that will continously check for new events
+    # from the server.
+    #
+    # @see #sync! See the documentation for {#sync!} for more information
+    #   and what happens in case of an error during sync.
+    def start_syncing
+      @sync_thread ||= Thread.new { loop { sync! } }
+    end
+
+    # Stops syncing against the homeserver.
+    def stop_syncing
+      return unless @sync_thread.is_a? Thread
+      @sync_thread.exit
+      @sync_thread.join
+      @sync_thread = nil
+    end
+
+    # Gets the user with the specified ID or display name.
+    #
+    # @return [User,nil] Returns a User object if the user could be found,
+    #   otherwise `nil`.
+    def get_user(id)
+      @users[id]
+    end
+
+    # Gets the room with the specified ID, alias, or name.
+    #
+    # @return [Room,nil] Returns a Room object if the room could be found,
+    #   otherwise `nil`.
+    def get_room(id)
+      @rooms[id]
+    end
+
+    private
+
+    # Syncs against the server.
+    #
+    # If an API error occurs during sync, it will be rescued and broadcasted
+    # as `:sync_error`.
+    def sync!
+      events = @matrix.sync since: @since
+      process_sync events
+    rescue ApiError => err
+      broadcast(:sync_error, err)
+    end
+
+    # Process the sync result.
+    #
+    # @param events [Hash] The events to sync.
+    def process_sync(events)
+      return unless events.is_a? Hash
+      @since = events['next_batch']
+      broadcast(:sync, events)
+
+      @rooms.process_events events['rooms'] if events.key? 'rooms'
+    end
+  end
+end

data/lib/chatrix/components/admin.rb

@@ -0,0 +1,58 @@
+require 'chatrix/user'
+
+module Chatrix
+  module Components
+    # Provides administrative actions for a room.
+    class Admin
+      # Initializes a new Admin instance.
+      #
+      # @param room [Room] The room to administrate.
+      # @param matrix [Matrix] Matrix API instance.
+      def initialize(room, matrix)
+        @room = room
+        @matrix = matrix
+      end
+
+      # Joins the room. Can only be used on public rooms or if the user
+      # has been invited.
+      def join
+        @matrix.rooms.actions.join @room.id
+      end
+
+      # Leaves the room. If the user is currently invited to the room,
+      # leaving the room is the same as rejecting the invite.
+      def leave
+        @matrix.rooms.actions.leave @room.id
+      end
+
+      # Kicks a user from the room.
+      #
+      # @param user [User,String] The user to kick, can be either a User
+      #   object or a String (user ID).
+      # @param reason [String] The reason for the kick.
+      # @return [Boolean] `true` if the user was kicked, otherwise `false`.
+      def kick(user, reason)
+        @matrix.rooms.actions.kick @room.id, user, reason
+      end
+
+      # Bans a user from the room.
+      #
+      # @param user [User,String] The user to kick, can be either a User
+      #   object or a String (user ID).
+      # @param reason [String] The reason for the ban.
+      # @return [Boolean] `true` if the user was kicked, otherwise `false`.
+      def ban(user, reason)
+        @matrix.rooms.actions.ban @room.id, user, reason
+      end
+
+      # Unbans a user from the room.
+      #
+      # @param user [User,String] The user to unban, can be either a User
+      #   objec or a String (user ID).
+      # @return [Boolean] `true` if the user was unbanned, otherwise `false`.
+      def unban(user)
+        @matrix.rooms.actions.unban @room.id, user
+      end
+    end
+  end
+end

data/lib/chatrix/components/messaging.rb

@@ -0,0 +1,42 @@
+module Chatrix
+  module Components
+    # Class to handle messaging actions for a room.
+    class Messaging
+      # Initializes a new Messaging instance.
+      # @param room [Room] The room to handle messaging for.
+      # @param matrix [Matrix] Matrix API instance.
+      def initialize(room, matrix)
+        @room = room
+        @matrix = matrix
+      end
+
+      # Sends a message to the room.
+      # @param message [String] The message to send.
+      # @return [String] Event ID for the send action.
+      def send_message(message)
+        @matrix.rooms.actions.send_message @room.id, message
+      end
+
+      # Sends a notice to the room.
+      # @param message [String] The notice to send.
+      # @return (see #send_message)
+      def send_notice(message)
+        @matrix.rooms.actions.send_message @room.id, message, 'm.notice'
+      end
+
+      # Sends an emote to the room.
+      # @param message [String] The emote text to send.
+      # @return (see #send_message)
+      def send_emote(message)
+        @matrix.rooms.actions.send_message @room.id, message, 'm.emote'
+      end
+
+      # Sends an HTML message to the room.
+      # @param message [String] The HTML formatted message to send.
+      # @return (see #send_message)
+      def send_html(message)
+        @matrix.rooms.actions.send_html @room.id, message
+      end
+    end
+  end
+end

data/lib/chatrix/components/permissions.rb

@@ -0,0 +1,55 @@
+require 'wisper'
+
+module Chatrix
+  module Components
+    # Helper for parsing permissions in a room.
+    class Permissions
+      include Wisper::Publisher
+
+      # Initializes a new Permissions instance.
+      # @param room [Room] The room that this permissions set belongs to.
+      def initialize(room)
+        @room = room
+        @actions = {}
+        @events = {}
+      end
+
+      # Updates permission data.
+      # @param content [Hash] New permission data.
+      def update(content)
+        @actions[:ban] = content['ban']
+        @actions[:kick] = content['kick']
+        @actions[:invite] = content['invite']
+        @actions[:redact] = content['redact']
+
+        content['events'].each do |event, level|
+          @events[event.match(/\w+$/).to_s.to_sym] = level
+        end
+
+        broadcast :update, @room, self
+      end
+
+      # Check if a user can perform an action.
+      #
+      # @param user [User] The user to test.
+      # @param action [Symbol] The action to check.
+      # @return [Boolean] `true` if the user can perform the action,
+      #   otherwise `false`.
+      def can?(user, action)
+        return false unless @actions.key? action
+        user.power_in(@room) >= @actions[action]
+      end
+
+      # Check if a user can set an event.
+      #
+      # @param user [User] The user to test.
+      # @param event [Symbol] The event to check.
+      # @return [Boolean] `true` if the user can set the event,
+      #   otherwise `false`.
+      def can_set?(user, event)
+        return false unless @events.key? event
+        user.power_in(@room) >= @events[event]
+      end
+    end
+  end
+end

data/lib/chatrix/components/state.rb

@@ -0,0 +1,160 @@
+require 'chatrix/events'
+
+require 'chatrix/components/permissions'
+
+require 'set'
+require 'wisper'
+
+module Chatrix
+  module Components
+    # Manages state for a room.
+    class State
+      include Wisper::Publisher
+
+      # @!attribute [r] canonical_alias
+      #   @return [String,nil] The canonical alias, or `nil` if none has
+      #     been set.
+      # @!attribute [r] name
+      #   @return [String,nil] The name, or `nil` if none has been set.
+      # @!attribute [r] topic
+      #   @return [String,nil] The topic, or `nil` if none has been set.
+      # @!attribute [r] creator
+      #   @return [User] The user who created the room.
+      # @!attribute [r] guest_access
+      #   @return [Boolean] `true` if guests are allowed in the room,
+      #     otherwise `false`.
+      # @!attribute [r] history_visibility
+      #   @return [String] The room's history visibility.
+      # @!attribute [r] join_rule
+      #   @return [String] Join rules for the room.
+      # @!attribute [r] permissions
+      #   @return [Permissions] Check room permissions.
+      attr_reader :canonical_alias, :name, :topic, :creator, :guest_access,
+                  :join_rule, :history_visibility, :permissions
+
+      # Initializes a new State instance.
+      #
+      # @param room [Room] The room the state belongs to.
+      # @param users [Users] The user manager.
+      def initialize(room, users)
+        @room = room
+        @users = users
+
+        @permissions = Permissions.new @room
+
+        @aliases = []
+        @members = Set.new
+      end
+
+      # Returns whether the specified user is a member of the room.
+      #
+      # @param user [User] The user to check.
+      # @return [Boolean] `true` if the user is a member of the room,
+      #   otherwise `false`.
+      def member?(user)
+        @members.member? user
+      end
+
+      # Updates the state with new event data.
+      # @param data [Hash] Event data.
+      def update(data)
+        data['events'].each { |e| process_event e } if data.key? 'events'
+      end
+
+      private
+
+      # Processes a state event.
+      # @param event [Hash] Event data.
+      def process_event(event)
+        return if Events.processed? event
+
+        name = 'handle_' + event['type'].match(/\w+$/).to_s
+        send(name, event) if respond_to? name, true
+
+        Events.processed event
+      end
+
+      # Handle the `m.room.create` event.
+      # @param event [Hash] Event data.
+      def handle_create(event)
+        @creator = @users.send(:get_user, event['content']['creator'])
+        broadcast :creator, @room, @creator
+      end
+
+      # Handle the `m.room.canonical_alias` event.
+      # @param (see #handle_create)
+      def handle_canonical_alias(event)
+        @canonical_alias = event['content']['alias']
+        broadcast :canonical_alias, @room, @canonical_alias
+      end
+
+      # Handle the `m.room.aliases` event.
+      # @param (see #handle_create)
+      def handle_aliases(event)
+        @aliases.replace event['content']['aliases']
+        broadcast :aliases, @room, @aliases
+      end
+
+      # Handle the `m.room.name` event.
+      # @param (see #handle_create)
+      def handle_name(event)
+        broadcast :name, @room, @name = event['content']['name']
+      end
+
+      # Handle the `m.room.topic` event.
+      # @param (see #handle_create)
+      def handle_topic(event)
+        broadcast :topic, @room, @topic = event['content']['topic']
+      end
+
+      # Handle the `m.room.guest_access` event.
+      # @param (see #handle_create)
+      def handle_guest_access(event)
+        @guest_access = event['content']['guest_access'] == 'can_join'
+        broadcast :guest_access, @room, @guest_access
+      end
+
+      # Handle the `m.room.history_visibility` event.
+      # @param (see #handle_create)
+      def handle_history_visibility(event)
+        @history_visibility = event['content']['history_visibility']
+        broadcast :history_visibility, @room, @history_visibility
+      end
+
+      # Handle the `m.room.join_rules` event.
+      # @param (see #handle_create)
+      def handle_join_rules(event)
+        @join_rule = event['content']['join_rule']
+        broadcast :join_rule, @room, @join_rule
+      end
+
+      # Process a member event.
+      # @param event [Hash] The member event.
+      def handle_member(event)
+        @users.process_member_event self, event
+        user = @users[event['sender']]
+        membership = event['content']['membership'].to_sym
+
+        # Don't process invite state change if the user is already a
+        # member in the room.
+        return if membership == :invite && member?(user)
+
+        if membership == :join
+          @members.add user
+        else
+          @members.delete user
+        end
+
+        broadcast(membership, @room, user)
+      end
+
+      # Process a power level event.
+      # @param event [Hash] Event data.
+      def handle_power_levels(event)
+        content = event['content']
+        @permissions.update content
+        @users.process_power_levels @room, content['users']
+      end
+    end
+  end
+end

data/lib/chatrix/components/timeline.rb

@@ -0,0 +1,50 @@
+require 'chatrix/message'
+require 'chatrix/events'
+
+require 'wisper'
+
+module Chatrix
+  module Components
+    # Manages the timeline for a room.
+    class Timeline
+      include Wisper::Publisher
+
+      # Initializes a new Timeline instance.
+      #
+      # @param room [Room] The room this timeline belongs to.
+      # @param users [Users] The user manager.
+      def initialize(room, users)
+        @room = room
+        @users = users
+      end
+
+      # Process timeline events.
+      # @param data [Hash] Events to process.
+      def update(data)
+        data['events'].each { |e| process_event e } if data.key? 'events'
+
+        # Pass the event data to state to handle any state updates
+        # in the timeline
+        @room.state.update data
+      end
+
+      private
+
+      # Processes a timeline event.
+      # @param event [Hash] Event data.
+      def process_event(event)
+        return if Events.processed? event
+        name = 'handle_' + event['type'].match(/\w+$/).to_s
+        send(name, event) if respond_to? name, true
+      end
+
+      # Process a message event.
+      # @param event [Hash] Event data.
+      def handle_message(event)
+        message = Message.new @users[event['sender']], event['content']
+        broadcast(:message, @room, message)
+        Events.processed event
+      end
+    end
+  end
+end