silicon 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b42a17f2843d05d79a364238d2acab60af7b58fb
-  data.tar.gz: 3ef558e06e125ce333da1076ecf95e07deed709b
+  metadata.gz: 7da11fceb3dbf78f8953e3971ac3125af7e5254c
+  data.tar.gz: 707b2eadfa9b4e814171e513342e2d4efee2579e
 SHA512:
-  metadata.gz: 6090adf8bb5518c4da8239908592d7be26aa35f7ae3af6c2b9c0d8ac2d2bb586ea5a99c9a2ac9e289820046c03400022d34a79d1b6090ca341c489c4258eeeeb
-  data.tar.gz: a9892ea638f31505e4df44368e26bee167c93ee040bdff42f70b2f58b8e01f6a1836f6308d57362b31c13b3c63154721ae2541d5bb39595211b6df727baefcb5
+  metadata.gz: 32062840418619974ae913c5dd9c3d818c8a57defbed2c936767237a15a4074ef177b8b19c7d0f067ed63badff31df205557ecd444c3ee653774aaeeb524df83
+  data.tar.gz: f65e787d25330b351b704c68710be73fcb55ff7cc0f0e1a81b82555d051ef05d27edb4ab32a0586d5c8fedfd040f25245042f8ea1a3b0744aca9b49e372b10ee

data/README.md

@@ -1,349 +1,121 @@
 # Silicon
+
 Silicon is a minimalistic web API framework. Its main idea is to implement an approach 
 from Clean Architecture principles - "web is just a delivery mechanism". 
 Silicon is build on top of IoC container Hypo and forces to use dependency injection 
-approach everywhere.    
-
-## Architecture
+approach everywhere.  
 
-![Silicon Architecture](https://user-images.githubusercontent.com/4575064/34541424-2b7b6c24-f0e9-11e7-8023-abc0df48c9c4.png)
+## Basic Concepts
 
-### Separation of Concerns
-
-Model-View-Controller (MVC) now is a sign of bad taste. Everybody who built more or less serious production
-web-application know that controllers become to be fat. Splitting controllers by context can a bit improve
-the situation but it's a visual trick, it still looks like:
+1. [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) is a heart of Silicon. Atomic actions can depend on request parameters, services, repositories, output of other 
+actions and other stuff. You can easily inject such dependencies in your actions through a constructor. 
+Dependency Injection significantly improves development experience: isolate your components, enjoy writing unit tests.
 
 ```ruby
-class UserController
-  def index
-    # ... 
+class LoadPost
+  def initialize(id, post_storage)
+    @id = id
+    @storage = post_storage
   end
   
-  def show
-    # ... 
-  end
-
-  def update
-    # ... 
-  end
-
-  # ...  
-end
-```  
-
-It roughly violates one of main OOP rules - [Single Responsibility Principle](). Somebody can say "controller is only intended
-to control the process of request handling", but it's too large responsibility. Actually it's responsible for creating,
-updating and deleting models, showing views, services invocation and so on. And it's an ideal picture. Usual situation is
-when domain code is located in controllers.
-Silicon replaces regular controllers with a chain of atomic actions. It doesn't protect you to use bad practices but
-allows to easily separate \[controller-\]actions. Every action is a simple brick:
-
-```ruby
-class ShowUsers
-  def call
-    # ...
-  end
-end
-
-class UpdateUser
   def call
-    # ...
+    @storage.find(@id)
   end
 end
-```
-
-A route can represent much more complicated logic containing several steps. For that purpose Silicon provides an ability
-to chain actions:
-
-```
-    -> update_user -> notify_admin -> log_action
-```
+```     
 
-Every of enumerated above actions are classes respond to method "call". More details about chains construction are  
-described below.
-   
-### Router
-
-Silicon Router is completely new vision of how to create flexible, lightweight, language-independent DSL for designing
-a schema of web-application routing. Rails, Hanami, Sinatra and others provide more or less visually similar DSL for
-defining routing schema. Their routers use Ruby blocks-based DSL for that. Ruby is a power, Ruby is a weakness:
-for such purpose Ruby is too verbose. An example demonstrating all features:   
+2. Instead of boring Ruby block-style routes definition like in Rails, Sinatra and others Silicon uses its 
+own language for that. Small example:
 
 ```
 :receive
     .->
-        /auth ->
-            :before -> load_current_user
-
-            /posts ->
-                GET -> list_posts
-                POST -> create_post
-
-                $id ->
-                    :before -> load_post
-
-                    GET -> show_post
-                    PATCH -> update_post -> :respond =200
-                    DELETE -> remove_post -> :respond =200
-
-                    /comments ->
-                        GET -> list_comments
-                        POST => add_comment => notify_author =* notify_subscribers -> :respond <- comment_plain =201
-
-                        $comment_id ->
-                            GET -> show_comment -> :respond <- comment
-                            DELETE -> remove_comment
+        :before -> load_current_user          
+        /posts ->
+            $id ->
+                :before -> load_post
+                /comments ->
+                    POST -> add_comment -> notify_author -> notify_subscribers -> :respond <- comment_test =201
 :catch -> handle_errors
-```  
-
-Routes configuration by default is located in file `app/app.routes`. You can change it's location in `silicon.yml` file.   
-
-#### Action path
-Routes definition has tree-like structure. There're two root entries - :receive and :catch.
-
-`:receive` section describes regular flow of incoming request.
-
-`:catch` section defines an action which calls when an error raised somewhere in the regular flow.
-
-`:receive` section should start from `.` - root point of the routing.
-
-Every line of the definition is a piece of path to target action or chain.
-
-Symbols `->` and `<TAB>` emulates directory structure. Configuration demonstrated above can be interpreted like:
-```
-    GET     /auth/posts/$id (show_post)
-    DELETE  /auth/posts/$id/comments/$comment_id (remove_comment)
-```
-Symbol `$` allows to receive request parameters.
- 
-#### Action chaining
-As you can see, some routes reference to a chain of actions, like:
-
-```
-    -> update_user -> notify_admin -> log_action
-```  
-It means that you can define a number of atomic operations in order to reach request goals.
-
-`->` is a simple sequential type of action. Process flow waits until finishing of it's execution before starting the next
-action or making a response.
-
-More interesting case:
-
-```
-    => add_comment => notify_author =* notify_subscribers
 ```
- 
-`=>` is a parallel operation. All parallel operations complete before the next sequential (`->`) or ending of the chain.
-
-`=*` is an asynchronous operation. It must not be completed before next sequential and even ending of the chain. 
 
-The time of execution of asynchronous and parallel operations can be limited in config file (by default it's 10 seconds). 
-
-#### Sending Response
-By default Silicon responds with HTTP status 200 (201 for POST) and empty body. You can define :respond instructions
-for sending custom status and specific response body:
+3. The combination of flexible router and dependency injection breaks existing dogmas. 
+Silicon framework introduces Abstract Chain pattern as a replacement for Model-View-Controller 
+and other ancient approaches. Every request handles by a set of atomic actions. 
 
 ```
-    ...
-    POST => add_comment => ... -> :respond <- comment_plain =201
+    # POST /posts/$id/comments
+    ... -> load_post -> add_comment -> ... 
 ``` 
 
-Expression `:respond <-` declares a view ("comment_plain") and a status `=` (201). Details about views formatting are described below.
-
-
-### Dependency Injection
-Dependency Injection (DI) is a heart of Silicon web-application. Every Silicon action can utilize known variables/entities 
-in the application. In example:
-
-when you have:
-
-```
-    GET /auth/posts/$id (show_post)
-```
-
-you can easily use request parameter:
-
 ```ruby
-class ShowPost
-  def initialize(id)
+class LoadPost
+  def initialize(id, post_storage)
     @id = id
+    @storage = post_storage
   end
   
   def call
-    # somehow extract a post using @id
-  end
-end
-```   
-
-Every action returns a result that automatically registers in the container and can be used in further actions:
-
-```
-    GET     /auth/posts/$id (load_post, show_post)
-```
-
-```ruby
-class ShowPost
-  def initialize(load_post_result)
-    @post = load_post_result
+    @storage.find(@id)
   end
-  # ...
-end
-```  
-
-You can customize the name of action result:
-
-```ruby
-class LoadPost
-  #...
+  
   def result_name
     'post'
   end 
 end
-```
-
-and use:
 
-```ruby
-class ShowPost
-  def initialize(post)
+class AddComment
+  def initialize(post, silicon_data, user, comment_storage)
     @post = post
+    @data = silicon_data
+    @user = user
+    @storage = comment_storage 
   end
   
-  # ...
+  def call
+    @storage.create(post: @post, message: @data[:message], user: @user)
+  end  
 end
 ```
 
-In order to support another types by DI you need to adjust the configuration `silicon.yml`:
-
-```
-path:
-  dependencies:
-    - actions # default location
-    - services/injectable # additional dependencies location
-```
-
-#### Objects lifetime
-As mentioned before, dependency injection is a heart of Silicon. And as you probably noticed we register dependencies 
-for every new request. In order to avoid leaking the memory for request-specific objects Silicon uses Hypo::Scope lifetime 
-style for registered objects. Every time when request is ending the dependencies remove from the container. 
+4. Silicon is a micro-framework for micro-services. It's not intended to create monolithic giants! 
+In terms of [Domain Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) 
+concepts one Silicon application should wrap only one [Bounded Context](https://en.wikipedia.org/wiki/Domain-driven_design#Bounded_context).
 
-BTW, using Hypo::Scope and it's `finalize` method definition you can implement 
-[Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) pattern. 
+## Getting Started
 
-```ruby
-class DbSession
-  include Hypo::Scope
-  
-  def initialize
-    @transaction = Transaction.new
-  end
+1. Install Silicon: 
 
-  def finalize
-    # unexpected behavior handling is in :catch section implementation
-    @transaction.commit      
-  end
-end
 ```
-
-### Views
-By default Silicon handles only JSON requests using [JBuilder](https://github.com/rails/jbuilder) engine. But you can extend a number of engines using
-method `add_view_builder` in your `app.rb`:
-
-```ruby
-class App < Silicon::App
- def initialize
-    super
-
-    add_view_builder(MyHtmlViewBuilder, 'html')
-  end
-end
+    $ gem install silicon
 ```
 
-View templates are located in `views` directory; you can change default location in `silicon.yml`:
+2. At the command prompt, create a new Silicon application:
+
 ```
-path:
-  views: custom/views/location
+    $ silicon new silicon-app
 ```
 
-In view template you can use any objects registered in the container. In example, you have a chain:
+3. Go to directory `silicon-app` and start the application using a server you prefer:
 
 ```
-    GET /posts/$id
-    -> load_user -> load_post -> load_comments -> :respond <- show_post
+    $ puma -p 8000 config.ru
 ```
 
-and it's implementation in Ruby:
+or just
 
-```ruby
-class LoadPost
-  def initialize(id)
-    @id = id
-  end
-    
-  def call
-    # Not a real ORM, just for the demo.
-    # Posts.find(id)
-  end
-    
-  def result_name
-    'post'
-  end
-end
-
-class LoadComments
-  def initialize(id)
-    @id = id
-  end
-    
-  def call
-    # Not a real ORM, just for the demo.
-    # Comments.where(post: post)
-  end
-    
-  def result_name
-    # as you probably noticed this annoying action can be replaced 
-    # with a convention in your own base class for application actions. 
-    # Also instead of this declaration you can still use default name 
-    # for actions like 'load_comments_result'.
-  
-    'comments'
-  end
-end
 ```
-
-Draw the view:
-
-```ruby
-json.post do
-  json.title @post.title
-  # ...
-  
-  json.comments @comments do |comment|
-    json.message comment.message
-    # ...
-  end
-end
+    $ rackup -p 8000 config.ru
 ```
 
-## Installation
-
-Add this line to your application's Gemfile:
+4. Using a browser, go to http://localhost:8000 and you'll see: 
 
-```ruby
-gem 'silicon'
+```json
+  {"message": "Welcome to silicon-app!"}
 ```
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install silicon
-    
-
-## Getting Started
+5. Investigate example application code, it will explain most of Silicon aspects.
+6. For more details visit our [Wiki](https://github.com/cylon-v/silicon/wiki).
 
 ## Development
 
@@ -353,9 +125,6 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 To install this gem onto your local machine, run `bundle exec rake install`. 
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## 
-
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/cylon-v/silicon.

data/lib/silicon/version.rb

@@ -1,3 +1,3 @@
 module Silicon
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: silicon
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Vladimir Kalinkin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-07 00:00:00.000000000 Z
+date: 2018-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hypo