teamspeak3 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5cfaad253891919553b8e8f9195e6c903a43e94f
-  data.tar.gz: 4b4a47e6af3efea58d63e32f004efb660eae2909
+  metadata.gz: 1f29c3659a40d129e7a749f5d3e91bc11530718f
+  data.tar.gz: f5c472bdbae695325c1882fa9231aaa5da62bac5
 SHA512:
-  metadata.gz: 4f2d97920b5994b11b4deb306296e9eef01e1f3d3d55ab62ea92e47e7de5acd3d55566c49e7be9d6becaa4907b391ce46938aaa10a48646121fb7e352c060288
-  data.tar.gz: a4e43cb8cb9ed5eb8c940e237102d6f9b95c6fdf436d9f31b01923dcfa62727a00c2817dc130553a1ea4db578a90ee35c94f956f4090528ff04a2951e6950837
+  metadata.gz: 7d125a3d63f88d2340357f42ff3860e15d18d8c284f7a682ae8213ab2c6a9926b8ddd9013dda593234c7feddabdfbffad32c6c4ebb7f047067c9d3a7ca6cd715
+  data.tar.gz: 80f2694136606027b437b7e19e2da9dd2e3c417e177900666f6da0959e5fe798eb0d1dfdf3f1979a73f181002d0e144e8bb9420c93723d2405e51aad5e852bb2

data/.rspec

@@ -0,0 +1 @@
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+## Release 0.0.4 (2018-03-11)
+
+* Add `TeamSpeak3::VERSION` to fetch the current version of this library.
+* Add `TeamSpeak3::Client#send_message` to allow to send messages directly via the client object
+  without going all the way down to the `TeamSpeak3::Server#send_message`
+* Add `TeamSpeak3::VirtualServer#execute` method which is basically a wrapper for `TeamSpeak3::Server#execute`
+  but it always sets the active virtual server correctly.
+* EOF errors will now be handled on connection attempts. (an EOF error will be raised when a connection has
+  been established but gets closed immediately)
+* Command execution on TeamSpeak 3 servers (TeamSpeak3::Server#execute) has been refactored.
+* Add `TeamSpeak3::Server#prepare_command` to build a command that can be executed safely (internally used by
+  `TeamSpeak3::Server#execute`)
+* Add `TeamSpeak3::ChannelCollection` that represents an array of channels for a virtual server (abstraction of `Array`)
+* `TeamSpeak3::VirtualServer#channels` now returns an instance of `TeamSpeak3::ChannelCollection`
+* Channels can now be created through `TeamSpeak3::ChannelCollection#create`
+* Channels can now be found with their ID via `TeamSpeak3::ChannelCollection#find`
+
+## Release 0.0.3 (cancelled/skipped)
+
+- This version has been cancelled and skipped -
+
+## Release 0.0.2 (2018-03-05)
+
+* `TeamSpeak3::VirtualServer` class was added to handle virtual servers.
+* `TeamSpeak3::Channel` class was added to handle channels on virtual servers.
+* `TeamSpeak3::Client` class was added to act on clients.
+* New `attr_reader`'s were added to `TeamSpeak3::Server` (`ip_address` and `query_port`)
+* Added `send_message_to` to class `TeamSpeak3::Server` to send messages to different targets (available targets: server, client, channel)
+* Added method `kick_client!` to `TeamSpeak3::Server` which is being used by the `TeamSpeak3::Client` class to kick clients from servers or channels.
+* Added `select_server` to `TeamSpeak3::Server` to select the current active virtual servers (this is required by the query interface of TeamSpeak 3). In general it should not be required to use this method at all because it's handled by the methods internally.
+
+## Release 0.0.1 (2018-03-04)
+
+* Add basic TeamSpeak 3 server connection handling

data/README.md

@@ -0,0 +1,34 @@
+# TeamSpeak 3 Query Library
+
+[![Gem Version](https://badge.fury.io/rb/teamspeak3.svg)](http://badge.fury.io/rb/teamspeak3)
+
+**NOTE: This library is currently being developed and should not be used for production purposes!**
+
+An OOP library to query and manage TeamSpeak 3 servers in Ruby.
+
+## Installation
+
+```
+gem install teamspeak3
+```
+
+## Getting Started
+
+```ruby
+require 'teamspeak3'
+
+server = TeamSpeak3::Server.new('127.0.0.1', 10011)
+server.login 'serveradmin', 'password'
+```
+
+## Contribution
+
+If you want to suggest new features or report bugs, feel free to open an issue [here](https://github.com/mschnitzer/teamspeak3/issues/new).
+
+If you want to contribute to the code base:
+
+1. Fork this repository
+2. Create a new branch
+3. Do your changes
+4. Push them to GitHub
+5. Open a pull request against the `master` branch

data/lib/channel.rb

@@ -57,6 +57,27 @@ module TeamSpeak3
       @max_family_clients = params[:channel_maxfamilyclients].to_i
     end
 
+    def self.create(virtual_server, name, opts = {})
+      command_parameters = { channel_name: name }
+
+      command_parameters[:channel_topic] = opts[:topic] if opts[:topic]
+      command_parameters[:channel_description] = opts[:description] if opts[:description]
+      command_parameters[:channel_password] = opts[:password] if opts[:password]
+      command_parameters[:channel_codec] = opts[:codec] if opts[:codec]
+      command_parameters[:channel_codec_quality] = opts[:codec_quality] if opts[:codec_quality]
+      command_parameters[:channel_maxclients] = opts[:max_clients] if opts[:max_clients]
+      command_parameters[:channel_maxfamilyclients] = opts[:max_family_clients] if opts[:max_family_clients]
+      command_parameters[:channel_order] = opts[:order] if opts[:order]
+      command_parameters[:channel_needed_talk_power] = opts[:needed_talk_power] if opts[:needed_talk_power]
+      command_parameters[:channel_name_phonetic] = opts[:name_phonetic] if opts[:name_phonetic]
+      command_parameters[:channel_icon_id] = opts[:icon_id] if opts[:icon_id]
+      command_parameters[:channel_codec_is_unencrypted] = opts[:codec_is_unencrypted] if opts[:codec_is_unencrypted]
+      command_parameters[:cpid] = opts[:parent_id] if opts[:parent_id]
+
+      response = virtual_server.execute :channelcreate, command_parameters
+      virtual_server.channels.find(response[:data].first[:cid])
+    end
+
     def codec_name
       return "Speex Narrowband" if @codec == 0
       return "Speex Wideband" if @codec == 1

data/lib/channel_collection.rb

@@ -0,0 +1,19 @@
+module TeamSpeak3
+  class ChannelCollection < Array
+    def initialize(virtual_server)
+      @virtual_server = virtual_server
+    end
+
+    def create(name, opts = {})
+      Channel.create(@virtual_server, name, opts)
+    end
+
+    def find(id)
+      self.each do |channel|
+        return channel if channel.id == id.to_i
+      end
+
+      nil
+    end
+  end
+end

data/lib/client.rb

@@ -111,6 +111,10 @@ module TeamSpeak3
       @recording
     end
 
+    def send_message(message)
+      virtual_server.server.send_message_to(self, message)
+    end
+
     def talker?
       @talker
     end

data/lib/command_parameter.rb

@@ -2,6 +2,7 @@ module TeamSpeak3
   module CommandParameter
     def self.encode(value)
       return unless value
+      value = value.to_s
 
       value.gsub!("\\", "\\\\")
       value.gsub!("/", "\/")
@@ -19,6 +20,7 @@ module TeamSpeak3
 
     def self.decode(value)
       return unless value
+      value = value.to_s
 
       value.gsub!("\\\\", "\\")
       value.gsub!("\/", "/")

data/lib/server.rb

@@ -19,14 +19,17 @@ module TeamSpeak3
           'Timeout' => @opts[:timeout] || 3,
           'Telnetmode' => false
         )
-        
-        @socket.waitfor(/Welcome to the TeamSpeak 3 ServerQuery interface/)
-      rescue Net::ReadTimeout => err 
+
+        @socket.waitfor("Match" => /Welcome to the TeamSpeak 3 ServerQuery interface/, "FailEOF" => true)
+      rescue Net::ReadTimeout
         raise TeamSpeak3::Exceptions::ServerConnectionFailed.new(@ip_address, @query_port, \
           "Timeout while waiting for TeamSpeak 3 welcome message.")
-      rescue Net::OpenTimeout, Errno::ECONNREFUSED => err
+      rescue Net::OpenTimeout, Errno::ECONNREFUSED
         raise TeamSpeak3::Exceptions::ServerConnectionFailed.new(@ip_address, @query_port, \
           "Could not open connection to server at #{@ip_address}:#{@query_port}")
+      rescue EOFError
+        raise TeamSpeak3::Exceptions::ServerConnectionFailed.new(@ip_address, @query_port, \
+          "Server closed the connection.")
       end
 
       true
@@ -36,7 +39,7 @@ module TeamSpeak3
       verify_connection
 
       begin
-        execute "login client_login_name=#{query_user} client_login_password=#{query_pass}"
+        execute :login, client_login_name: query_user, client_login_password: query_pass
       rescue TeamSpeak3::Exceptions::CommandExecutionFailed => err
         raise TeamSpeak3::Exceptions::QueryLoginFailed, err.message
       end
@@ -45,14 +48,14 @@ module TeamSpeak3
     end
 
     def select_server(virtual_server_id)
-      execute "use sid=#{virtual_server_id}"
+      execute :use, sid: virtual_server_id
       @active_server = virtual_server_id
     end
 
     def virtual_servers
       server_list = []
 
-      servers = execute "serverlist -uid -all"
+      servers = execute :serverlist, options: [:uid, :all]
       servers[:data].each do |server|
         server_list << TeamSpeak3::VirtualServer.new(self, server)
       end
@@ -61,26 +64,13 @@ module TeamSpeak3
     end
 
     def kick_client!(client_id, action, reason = nil)
-      # set correct kick action
       action_id = nil
       action_id = 4 if action == :channel
       action_id = 5 if action == :server
 
       raise TeamSpeak3::Exceptions::InvalidKickAction.new(action) unless action_id
 
-      # handle multiple client ids
-      client_ids = ""
-      if client_id.is_a?(Integer)
-        client_ids = "clid=#{client_id}"
-      elsif client_id.is_a?(Array)
-        client_id.each { |id| client_ids += "clid=#{id}|" }
-        client_ids = client_ids[0..-2]
-      end
-
-      # execute command
-      command = "clientkick #{client_ids} reasonid=#{action_id}"
-      command += " reasonmsg=#{TeamSpeak3::CommandParameter.encode(reason)}" if reason
-      execute command
+      execute :clientkick, clid: client_id, reasonid: action_id, reasonmsg: reason
     end
 
     def send_message_to(target, message, target_type = :auto)
@@ -94,6 +84,11 @@ module TeamSpeak3
           target_id = target.id
           target_type_id = 2
 
+          select_server target.virtual_server.id
+        elsif target.is_a?(TeamSpeak3::Client)
+          target_id = target.client_id
+          target_type_id = 1
+
           select_server target.virtual_server.id
         else
           raise TeamSpeak3::Exceptions::InvalidTarget.new(target)
@@ -108,13 +103,43 @@ module TeamSpeak3
         raise TeamSpeak3::Exceptions::InvalidTargetType.new(target_type) unless target_type_id
       end
 
-      execute "sendtextmessage target=#{target_id} targetmode=#{target_type_id} " \
-        "msg=#{TeamSpeak3::CommandParameter.encode(message)}"
+      execute :sendtextmessage, target: target_id, targetmode: target_type_id, msg: message
       true
     end
 
-    def execute(command)
-      @socket.puts(command)
+    def prepare_command(command, params = {})
+      prepared_command = command.to_s
+
+      if params[:options]
+        raise ArgumentError, 'options must be an array!' unless params[:options].is_a?(Array)
+
+        params[:options].each do |option|
+          prepared_command += " -#{option}"
+        end
+      end
+
+      params.each do |param, value|
+        next if param == :options
+
+        if value.is_a?(Array)
+          prepared_command += ' '
+
+          value.each do |v|
+            prepared_command += "#{param}=#{TeamSpeak3::CommandParameter.encode(v)}|"
+          end
+
+          prepared_command = prepared_command[0..-2]
+        else
+          prepared_command += " #{param}=#{TeamSpeak3::CommandParameter.encode(value)}"
+        end
+      end
+
+      prepared_command
+    end
+
+    def execute(command, params = {})
+      prepared_command = prepare_command(command, params)
+      @socket.puts(prepared_command)
 
       # every response contains an error information. so we wait until we receive a response
       response = @socket.waitfor(/error id=.*/)
@@ -124,7 +149,7 @@ module TeamSpeak3
         raise TeamSpeak3::Exceptions::CommandExecutionFailed.new(
           response[:errors][:id],
           response[:errors][:msg],
-          command,
+          prepared_command,
         )
       end
 

data/lib/teamspeak3.rb

@@ -1,10 +1,15 @@
 require 'net/telnet'
 
+module TeamSpeak3
+  VERSION = "0.0.4"
+end
+
 # exceptions shall be required first
 require_relative 'exceptions.rb'
 
 # library classes ordered alphabetically
 require_relative 'channel.rb'
+require_relative 'channel_collection.rb'
 require_relative 'client.rb'
 require_relative 'command_parameter.rb'
 require_relative 'virtual_server.rb'

data/lib/virtual_server.rb

@@ -29,23 +29,19 @@ module TeamSpeak3
     end
 
     def channels
-      check_active_server
-
-      channels_list = []
-      channels = @server.execute "channellist -topic -flags -voice -limits -icon"
+      channels_list = ChannelCollection.new(self)
+      channels = execute :channellist, options: [:topic, :flags, :voice, :limits, :icon]
 
       channels[:data].each do |channel|
-        channels_list << TeamSpeak3::Channel.new(self, channel)
+        channels_list << Channel.new(self, channel)
       end
 
       channels_list
     end
 
     def clients
-      check_active_server
-
       clients_list = []
-      clients = @server.execute "clientlist -uid -away -voice -times -groups -info -icon -country"
+      clients = execute :clientlist, options: [:uid, :away, :voice, :times, :groups, :info, :icon, :country]
 
       clients[:data].each do |client|
         clients_list << TeamSpeak3::Client.new(self, client)
@@ -58,6 +54,11 @@ module TeamSpeak3
       server.send_message_to(self, message)
     end
 
+    def execute(command, params = {})
+      check_active_server
+      @server.execute(command, params)
+    end
+
     def ==(target)
       @id == target
     end

data/spec/factories/server.rb

@@ -0,0 +1,9 @@
+FactoryBot.define do
+  factory :server, class: TeamSpeak3::Server do
+    ip_address '127.0.0.1'
+    query_port 10011
+    timeout 2
+
+    initialize_with { new(ip_address, query_port, timeout: timeout) }
+  end
+end

data/spec/server_spec.rb

@@ -0,0 +1,88 @@
+require_relative 'spec_helper.rb'
+require 'socket'
+
+describe TeamSpeak3::Server do
+  describe '#initialize' do
+    context 'attr_reader' do
+      let(:server) { FactoryBot.build(:server) }
+
+      it { expect(server.ip_address).to eq('127.0.0.1') }
+      it { expect(server.query_port).to eq(10011) }
+    end
+  end
+
+  describe '#connect' do
+    let(:query_port) { rand(50000..60000) }
+    let(:server) { FactoryBot.build(:server, ip_address: '127.0.0.1', query_port: query_port) }
+
+    describe 'telnet connection' do
+      context 'for a valid TeamSpeak 3 server' do
+        before do
+          # spawn a tcp server for connection tests
+          Thread.new(query_port) do |query_port|
+            tcp_server = TCPServer.new('127.0.0.1', query_port)
+            client = tcp_server.accept
+            client.puts "Welcome to the TeamSpeak 3 ServerQuery interface"
+            sleep 3
+            client.close
+            tcp_server.close
+          end
+
+          # it takes a moment till the server has spawned
+          sleep 2
+        end
+
+        it { expect { server.connect }.to_not raise_error }
+      end
+
+      context 'for a non-TeamSpeak 3 server' do
+        before do
+          # spawn a tcp server for connection tests
+          Thread.new(query_port) do |query_port|
+            tcp_server = TCPServer.new('127.0.0.1', query_port)
+            client = tcp_server.accept
+            client.puts "I'm not a TeamSpeak 3 server"
+            sleep 3
+            client.close
+            tcp_server.close
+          end
+
+          # it takes a moment till the server has spawned
+          sleep 2
+        end
+
+        it { expect { server.connect }.to raise_error(TeamSpeak3::Exceptions::ServerConnectionFailed, /welcome message/) }
+      end
+    end
+  end
+
+  describe '#prepare_command' do
+    let(:server) { FactoryBot.build(:server) }
+
+    context 'with options' do
+      it { expect(server.prepare_command(:clientlist, options: [:uid, :away, :voice])).to eq('clientlist -uid -away -voice') }
+    end
+
+    context 'with parameters' do
+      it { expect(server.prepare_command(:clientlist, argument1: 'hello', argument2: 'test')).to \
+                  eq('clientlist argument1=hello argument2=test') }
+    end
+
+    context 'with parameters and options' do
+      it { expect(server.prepare_command(:clientlist, argument1: 'hello', argument2: 'test', options: [:uid, :flags])).to \
+                  eq('clientlist -uid -flags argument1=hello argument2=test') }
+    end
+
+    context 'with arrays as parameters' do
+      it { expect(server.prepare_command(:clientkick, clid: [1,2,3], argument2: 'test')).to \
+                  eq('clientkick clid=1|clid=2|clid=3 argument2=test') }
+    end
+
+    context 'argument encoding' do
+      it { expect(server.prepare_command(:clientkick, argument1: 'I need | encoding!!')).to \
+           eq("clientkick argument1=I\\sneed\\s\\p\\sencoding!!") }
+      it { expect(server.prepare_command(:clientkick, argument: ['I need | encoding!!', 'me | too!!'])).to \
+           eq("clientkick argument=I\\sneed\\s\\p\\sencoding!!|argument=me\\s\\p\\stoo!!") }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require_relative '../lib/teamspeak3.rb'
+require 'factory_bot'
+
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+
+  config.before(:suite) do
+    FactoryBot.find_definitions
+  end
+end

metadata

@@ -1,22 +1,86 @@
 --- !ruby/object:Gem::Specification
 name: teamspeak3
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Manuel Schnitzer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-05 00:00:00.000000000 Z
-dependencies: []
+date: 2018-03-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-telnet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.8.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.8.2
 description: An OOP library to query and manage TeamSpeak 3 servers in Ruby.
 email: webmaster@mschnitzer.de
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
+- CHANGELOG.md
+- README.md
 - lib/channel.rb
+- lib/channel_collection.rb
 - lib/client.rb
 - lib/command_parameter.rb
 - lib/exceptions.rb
@@ -32,6 +96,9 @@ files:
 - lib/server_response.rb
 - lib/teamspeak3.rb
 - lib/virtual_server.rb
+- spec/factories/server.rb
+- spec/server_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/mschnitzer/teamspeak3
 licenses:
 - MIT