tamashii-client 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a57eb1ba451079455f62b8ddf5ae3dc426f8070d
-  data.tar.gz: 459efd6811a65e156a0edc476cd0262d6fccd886
+  metadata.gz: 616b8acc7d50fcb48f9b8e3cd333fd664e41e9cb
+  data.tar.gz: 0c4529a5ee7eee3844f6cad3d05052d01b656526
 SHA512:
-  metadata.gz: b5f9a314e6d792de8a9a934a9ce5448bc1220e819b5f03123562c6fdf556f3d4d7cc2b8bb16d54b6d61e87769b860936efd803af16a92dee02cd052a4b9149b3
-  data.tar.gz: ed7b1cb8340d8494b5fe4e8d9fadfe6607ff767849d08b0db600cc271d9cd0adcc2d3432442d0a3ecd48af88ed35ebd3de65805d88f13a2785c9890d2abc4134
+  metadata.gz: 3e329f34d53186908f64c96143acc0ba3dcd7d657f8d85957a204bdc9c12b1cf8638a3b8611409f5fb99a16d845e22c2dbfdcaf3b0b4e8f0118bf2531700fc60
+  data.tar.gz: 11f3285f16c6d6634603cc1b82b8ebd60ebd9ee61e3e71ce60c1e62be832eb06f7353086a9937944763e9187eb6ca7f926d5560c453393dbbc2a95f0a839a0a8

data/README.md

@@ -1 +1,181 @@
-# Tamashii::Client
+---
+tags: tamashii, readme
+---
+
+Tamashii Client [![Gem Version](https://badge.fury.io/rb/tamashii-client.svg)](https://badge.fury.io/rb/tamashii-client) 
+===
+
+Tamashii Client is the client side of the WebSocket framework [Tamashii](https://github.com/tamashii-io/tamashii). It is event-driven and it provides high-level API for users to communicates with WebSocket server easily. 
+
+## Installation
+
+Add the following code to your `Gemfile`
+
+And then execute:
+```ruby
+$ bundle install
+```
+
+Or install it yourself with:
+```ruby
+$ gem install tamashii-client
+```
+
+## Usage
+
+With Tamashii Client, we just need to focus on how to handle the events such as `on_connect` for connection opened or `on_message` for receiving messages from server.
+
+### Simple Example
+
+A simple example of using Tamashii Client follows. Here we will connect to the [wss://echo.websocket.org](wss://echo.websocket.org), the echo testing for WebSocket.
+
+```ruby
+require 'tamashii/client'
+
+# configuration for client. Can be seperated into other file
+Tamashii::Client.config do
+  # whether to use TLS or not. Here we connect to 'wss', so the value is true
+  use_ssl true
+  # the hostname WITHOUT url scheme
+  host "echo.websocket.org"
+  # the port to connect with. 443 for HTTPS and WSS
+  # Note the current version client does not infer the port from 'use_ssl'
+  # So you must explictly specifiy the port to use
+  port 443
+  # the log file for internel connection log 
+  # default is STDOUT
+  log_file 'tamashii.log'
+end
+
+client = Tamashii::Client::Base.new
+@server_opened = false 
+
+# callback for server opened
+# called when the WebSocket connection is readt
+client.on(:open) do  
+  @server_opened = true
+end
+# callback for receving messages
+# The data received is represented in a byte array
+# You may need to 'pack' it back to Ruby string
+client.on(:message) do |message|
+  puts "Received: #{message.pack('C*')}"
+end
+
+
+# sending loop
+# We send a request to server every second and terminates after 10 seconds
+# In the begining, the server is not opened so the sending may fail.
+count = 0 
+loop do
+  sleep 1
+  if @server_opened # can also use 'client.opened?'
+    client.transmit "Hello World! #{count}"
+  else
+    puts "Unable to send #{count}: server not opened"
+  end 
+  count += 1
+  if count >= 10
+    client.close
+    break
+  end 
+end
+```
+
+The [wss://echo.websocket.org](wss://echo.websocket.org) will echo the messages back to the client. So if everything works fine, you will see following output:
+
+```text
+Unable to send 0: server not opened
+Received: Hello World! 1
+Received: Hello World! 2
+Received: Hello World! 3
+Received: Hello World! 4
+Received: Hello World! 5
+Received: Hello World! 6
+Received: Hello World! 7
+Received: Hello World! 8
+Received: Hello World! 9
+```
+
+If you look into the log file (`tamashii.log` in this example), you can find the connection details of Tamashii Client.
+
+```log
+[2017-09-08 03:39:38] INFO -- WebSocket Client  : Worker Create!
+[2017-09-08 03:39:39] INFO -- WebSocket Client  : Trying to open the socket...
+[2017-09-08 03:39:40] INFO -- WebSocket Client  : Socket opened!
+[2017-09-08 03:39:40] INFO -- WebSocket Client  : WebSocket Server opened
+[2017-09-08 03:39:41] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 49]
+[2017-09-08 03:39:41] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 50]
+[2017-09-08 03:39:42] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 51]
+[2017-09-08 03:39:43] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 52]
+[2017-09-08 03:39:44] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 53]
+[2017-09-08 03:39:45] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 54]
+[2017-09-08 03:39:46] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 55]
+[2017-09-08 03:39:47] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 56]
+[2017-09-08 03:39:48] DEBUG -- WebSocket Client : Message from server: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33, 32, 57]
+[2017-09-08 03:39:49] INFO -- WebSocket Client  : WebSocket Server closed
+[2017-09-08 03:39:49] INFO -- WebSocket Client  : Socket closed
+[2017-09-08 03:39:49] DEBUG -- WebSocket Client : Worker terminales normally
+```
+
+The log level can be changed in the configuration using `log_level`. For example, to change to level to `INFO`:
+```ruby
+Tamashii::Client.config do
+  log_level :INFO
+end
+```
+
+### The events and callbacks
+
+These are events in the Tamashii Client. You can use `on` method to register callbacks for them. 
+- `socket_opened`
+    - When the low-level io socket (`TCPSocket` or `OpenSSL::SSL::SSLSocket`) successfully connected to the server. 
+    - Receving this event does not imply the server supports WebSocket.
+- `open`
+    - When the WebSocket handshake is finished and the connection is opened
+    - Client can start sending data to server after receiving this event.
+- `message`
+    - When the client receives the WebSocket payload from server.
+    - The message payload will be pass as the argument of the callback.
+- `error`
+    - When there is a protocol error due to bad data sent by the other peer.
+    - This event is purely informational, you do not need to implement error recovery.
+    - The error object will be pass as the argument of the callback.
+- `close`
+    - When the WebSocket is closed **normally**. 
+    - Will **NOT** be fired when the connection is closed by low-level IO error such as connection reset. 
+- `socket_closed`
+    - When the low-level socket is closed. 
+    - Will be fired no matter the WebSocket is closed normally or not.
+
+
+
+### Cooperate with Tamashii Server
+
+Above example using the [wss://echo.websocket.org](wss://echo.websocket.org) to test your client. You can also use the [Tamashii](https://github.com/tamashii-io/tamashii) server to test your client. Only thing to do is to change the `host` and `port` in the configuration into the one used by your Tamashii server. 
+
+## Development
+
+To get the source code
+
+    $ git clone git@github.com:tamashii-io/tamashii-client.git
+
+Initialize the development environment
+
+    $ ./bin/setup
+
+Run the spec
+
+    $ rspec
+
+Installation the version of development on localhost
+
+    $ bundle exec rake install
+
+## Contribution
+
+Please report to us on [Github](https://github.com/tamashii-io/tamashii-client) if there is any bug or suggested modified.
+
+The project was developed by [5xruby Inc.](https://5xruby.tw/)
+
+

data/lib/tamashii/client/base.rb

@@ -20,7 +20,8 @@ module Tamashii
       end
 
       def initialize
-        @url = "#{Config.use_ssl ? "wss" : "ws"}://#{Config.host}:#{Config.port}/#{Config.entry_point}"
+        entry_point_with_slash = Config.entry_point.start_with?("/") ? Config.entry_point : "/#{Config.entry_point}"
+        @url = "#{Config.use_ssl ? "wss" : "ws"}://#{Config.host}:#{Config.port}#{entry_point_with_slash}"
 
         @callbacks = {}
 

data/lib/tamashii/client/config.rb

@@ -5,12 +5,12 @@ module Tamashii
       register :log_file, STDOUT
 
       register :use_ssl, false
-      register :entry_point, "/tamashii"
+      register :entry_point, ""
       register :host, "localhost"
       register :port, 3000
-      register :opening_timeout, 5
+      register :opening_timeout, 10
       register :opening_retry_interval, 1
-      register :closing_timeout, 5
+      register :closing_timeout, 10
 
       def log_level(level = nil)
         return Client.logger.level if level.nil?

data/lib/tamashii/client/version.rb

@@ -1,5 +1,5 @@
 module Tamashii
   module Client
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tamashii-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - 蒼時弦也
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-06 00:00:00.000000000 Z
+date: 2017-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: websocket-driver