README.md in tamashii-client-0.1.0 vs README.md in tamashii-client-0.1.1
- old
+ new
@@ -1,180 +1,360 @@
-# Tamashii::Client
+---
+tags: tamashii, readme
+---
+
+Tamashii Client [](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/)
+
+