toycol 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94c69c1ed2726e69431304ff3c4fb727581b7893160d5dbe085731f4d85dfce2
-  data.tar.gz: 94fc2c13fbd5149a47669a521dfa40377e1edf890a92b33468bf534c6d34ed45
+  metadata.gz: b1b8a58a4fd3f08fc0efe5c808ed00f1fdd78e66b8b0c5467f4deb314f504fde
+  data.tar.gz: 86c53cfa48a4331cde4e5888b92a28645bb88b81695b8996b0ef301958364575
 SHA512:
-  metadata.gz: c5c3d01ea2c3b41491e3d365b781d92677ef027ce9fefa1d45b3ab360e947416035c39d5c9d32dd29ae01c309dfa27338097e5a63dfcd248aa9647b45784bb28
-  data.tar.gz: d09afa0497d2b40fcc0b404a19ceee343b9f132a434cbf80feef1cac3bbef060397bccc15503beb507be6e0b03d33b6d5f5cdbe96c5499a093b3a8a27dbd8f24
+  metadata.gz: 6f98b7f6753378032835b787f2f46c1679d6d5df5b88188a1e8f4350ae486146cad37ea1b8f67ec2af0d6f91e8ed24015154a2048f5891d4fb89f662ae912aee
+  data.tar.gz: '054893839fdaea8dfb45701e1f2a0cca55c19287e03d18a9266f2547502bb4c18d4fe97b822960aeef208044660e30262bc89945d269a047f3c6398c954c99e8'

data/CHANGELOG.md

@@ -1,5 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. For info on how to format all future additions to this file please reference [Keep A Changelog](https://keepachangelog.com/en/1.0.0/).
+
 ## [Unreleased]
 
-## [0.0.1] - 2021-07-12
+## [1.0.0] - 2021-07-27
+
+The first major release of Toycol.The main features are:
 
-- Initial release
+- [Added] Toycol::Protocol - For defining orignal application protocol
+- [Added] Toycol::Proxy - For accepting requests and pass them to the background server
+- [Added] Toycol::Command - For user friendly CLI
+  - `$ toycol server` - For starting proxy & background server
+  - `$ toycol client` - For sending request message to server
+  - `$ toycol generate` - For generating skeletons of Protocolfile & application
+- [Added] Toycol::Server - As a built-in background server
+- [Added] Rack::Handler::Toycol - For running Rack compartible application & switching background server

data/README.md

@@ -1,13 +1,122 @@
 # Toycol
 
-Toy Application Protocol framework
+Toycol is a small framework for defining toy application protocols.
+
+You can define your own application protocol only by writing a parser in Toycol DSL for request messages.
+
+Since the server and client programs to run the protocol are built-in from the beginning, you only need to prepare the following two items to run your custom protocol.
+- A configuration file named like `Protocolfile`, `Protocolfile.protocol_name` and so on
+- A Rack compartible application(e.g. `config.ru`)
+
+In the real world, there is (yet) no full-fledged web server or browser in the world that runs on the custom protocol you devised.
+Therefore, the protocol defined by this framework is in fact a "toy".
+However, by using this framework, you will be able to experience and learn how the connection between the application layer and the transport layer is, and how the application protocol works on the transport layer.
+
+## Example(on original "Duck" protocol)
+
+In this protocol:
+  - Client would send message like: `"quack, quack /posts<3user_id=1"`
+  - Server would interpret client message: `"GET /posts?user_id=1"`
+
+You write your definition in Protocolfile
+
+```ruby
+# Protocolfile.duck (protocol file)
+
+Protocol.define(:duck) do
+  # [OPTIONAL] You can add your original request methods
+  add_request_methods "OTHER"
+
+  # [OPTIONAL] You can define your custom status codes
+  custom_status_codes(
+    600 => "I'm afraid you are not a duck..."
+  )
+
+  # [REQUIRED] Define how you parse request path from request message
+  request.path do |message|
+    %r{(?<path>\/\w*)}.match(message)[:path]
+  end
+
+  # [REQUIRED] Define how you parse query from request message
+  request.query do |message|
+    %r{\<3(?<query>.+)}.match(message) { |m| m[:query] }
+  end
+
+  # [REQUIRED] Define how you parse query from request message
+  request.http_method do |message|
+    case message.scan(/quack/).size
+    when 2 then "GET"
+    else "OTHER"
+    end
+  end
+end
+```
+
+Don't forget, you need to prepare your application as well.
+
+```ruby
+# config_duck.ru (Rack compartible application)
+
+require "rack"
+require "toycol"
+
+# Specify which protocol to use
+Toycol::Protocol.use(:duck)
+
+class App
+  def call(env)
+    case env["REQUEST_METHOD"]
+    when "GET"
+      [
+        200,
+        { "Content-Type" => "text/html" },
+        ["Quack, Quack! This app is running by Duck protocol."]
+      ]
+    when "OTHER"
+      [
+        600,
+        { "Content-Type" => "text/html" },
+        ["Sorry, this application is only for ducks...\n"]
+      ]
+    end
+  end
+end
+
+run App.new
+```
+
+Then you run server & client
+
+```
+# In terminal for server
+
+$ toycol server config_duck.ru
+Toycol starts build-in server, listening on unix:///tmp/toycol.socket
+Toycol is running on localhost:9292
+=> Use Ctrl-C to stop
+```
+
+```
+# In other terminal for client
+
+$ toycol client "quack, quack /posts<3user_id=1"
+[Toycol] Sent request message: quack, quack /posts<3user_id=1
+---
+[Toycol] Received response message:
+
+HTTP/1.1 200 OK
+Content-Type: text/html
+Content-Length: 32
+
+Quack, Quack! This app is running by Duck protocol.
+```
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'toycol'
+gem "toycol"
 ```
 
 And then execute:
@@ -20,7 +129,64 @@ Or install it yourself as:
 
 ## Usage
 
-WIP
+Toycol provides useful commands to define & run your protocol.
+
+#### `toycol generate` - To define your new protocol
+
+You can use `toycol generate` command to generate skeletons of Protocolfile and application.
+
+```
+$ toycol generate PROTOCOL_NAME
+```
+
+When you run this command, skeletons of `Protocolfile.PROTOCOL_NAME` and `config_PROTOCOL_NAME.ru` will be generated.
+If you only need one of them, you can specify the type by `-t` option.
+
+```
+$ toycol generate PROTOCOL_NAME -t protocol
+# or
+$ toycol generate PROTOCOL_NAME -t app
+```
+
+If `PROTOCOL_NAME` is not specified, Protocolfile and config.ru will simply be generated.
+
+```
+$ toycol generate
+```
+
+#### `toycol server` - To run server by your protocol
+
+After you prepare Protocolfile & application, you need to start server to run the application by `toycol server` command.
+
+```
+# Please specify application file name
+$ toycol server config_`PROTOCOL_NAME`.ru
+```
+
+Then the server will start.
+
+Normally, `toycol server` command will start the server built into toycol.
+However, if Puma is already installed in your environment, it will start Puma by default.
+
+If you want to explicitly specify which server to use, you can use the -u option.
+
+```
+$ toycol server config_`PROTOCOL_NAME`.ru -u puma
+# or
+$ toycol server config_`PROTOCOL_NAME`.ru -u buid_in
+```
+
+If you would like to check other options, run the command `toycol server -h`.
+
+#### `toycol client` - To send request message by your protocol
+
+When you would like to send the request message to the server, use `toycol client`.
+
+```
+$ toycol client "YOUR REQUEST MESSAGE"
+```
+
+If you would like to check other options, run the command `toycol client -h`.
 
 ## Development
 

data/lib/toycol/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toycol
-  VERSION = "0.3.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toycol
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Misaki Shioi