utter 1.0.6 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aaca52bdee87dcd076358931bbb3f331b439b609
-  data.tar.gz: 546fcac5095b7da7c2be234db664503cc04fce3c
+  metadata.gz: f0200b470531e6b81be6eaaf1996ccf285d33a3b
+  data.tar.gz: 6f4925e7644d3125fb601e57624c04e34e006f68
 SHA512:
-  metadata.gz: acb9d767cd45681d665a0407d96c37cdb9019cd23982e772e4e0e1ab3cd1cf9e5971dcedcb7ed8cdef196ccf070469dd86c67645d742f5291a18a6eea5bb7963
-  data.tar.gz: 7707900d5300e69d7e3909fd0ba8a6c1c0552684673a5c163dcc8dbc1f0636c5e1227576de6d61c5c751ab0ea4f9edd96a6f4ad7f2de933c19deaf078b279eef
+  metadata.gz: f0cab0ac0c1a72a2e71a89fc810246a1c269a71327b0a0e2c814c49212a4880d5850cfe75d2b381b0a937287ca12f3677ccdc93443d569ec0b6904f8b2718d15
+  data.tar.gz: 09419fd90b9b0cb6c93424056274b15f20a056ad2b563477055a6d897bf65dc74936936fe9c960debe53b80b0c9e7d535069cf35e3374abc514e5ae6f0c1b226

data/README.md

@@ -1,19 +1,253 @@
-Utter
-=====
+What is Utter?
+==============
+Utter is a Domain-specific Microservices Framework written in Ruby for building both regular and advanced Rule-based web APIs.
+
+
+What is a Domain-specific Microservice?
+========================================
+A domain is an area of knowledge such as an industry field or a subject of interest.
+Building an application often requires the utilization of knowledge from a number of different domains. 
+
+Utter as a tool is used to manifest the implementation of an Application Model into a number of isolated domains, each refereed to as a `Domain-specific Microservice`.
+
+A Domain-specific Microservice provides an isolation of a domain via defining its bounded context within a single service. 
+Such isolation supports the inhabitance of autonomous small teams. 
+
+Autonomous small teams are more capable of defining and hence understanding the problems involved within a bounded-context domain. 
+
+As business-inhereted intricate problems on domain basis it is easier to define domain basis as opposed to the much more difficult to define application-as-a-whole basis.
+
+Each Utter Domain-specific Microservice incorporate its Domain-specific knowledge via extensions. 
+
+
+Utter is a - Simplicity Fuck'n Matters - microservies framework for building fun-sized independently deployable services.
+
+Via using Utter each microservice, you create shall exhibit the following Domain-Driven Design coherences:
+• Complete functionally Resource representation
+• Append-only Data management
+• Each microservice handles one resource (or verb), e.g Clients, Shop Items, Carts, Checkout, etc.
+- minmizes the number of choices of Design Patterns per service.
+
+fully acknowldges the philosphy of ... with the caveats of ...
+
+- seperate reading data from writing data.
+
+
+autonomous small teams, advocating complex pieces of logic should have ,  intricate
+
+A Domain-specific Microservice is a declarative Rule-based web service, in the sense that allows a client to interact with it via a Domain-speific Ubiquitous Language(DDD) that changes the state of the system it represents.
+
+In the same sense that natural langauges evolve while preserving its grammer rules, the Domain-specific Ubiquitious Language have a schema which acts as its grammer, or syntax if you may.
+
+
+The format of the DUL is JSON, making it easily interchangable among different systems and the microservice components.
+
+Example
+#{events: [
+#{facts: [
+#{productions: [
+#{production_rules: [
+{rules: [
+  {subject: {name: "3am abdo", type: "souq"}, predicat: {action: "wants"}, object: {service: "delivery", type: "cup of tea", quantity: "1" }},
+  {subject: {name: "ss", age: "11"}, predicat: {action: kill, method: car accident}, object: {name: "john", age: "33"}},
+  {subject: {name: "ss", age: "11"}, predicat: {action: kill, method: car accident}, object: {name: "john", age: "33"}},
+  {subject: {name: "ss", age: "11"}, predicat: {action: kill, method: car accident}, object: {name: "john", age: "33"}}
+]}
+
+#Declarative microservice means that events changing the state of the system are domain-specific yet indepentant from the technologies(languages\libraries\frameworks) used to implement the microservice. A level of abstraction for interfacing with the domain and not with the implmention technologies. 
+
+
+#Utter define a 'Declarative API' as an API that consists of a number of microservices, that takes a JSON payload of "events" form an API client that declares what the system should do (as opposed to how it should do it) and the backend of the API carries the exact same results regardless of the techinical details (implmentation language (ruby, python, etc.) or frameworks used).
+
+
+Rules allow us to represent certain kinds of knowledge that are difficult to employ a conventional procedural program. 
+Rule-based programs also separate the knowledge from the rest of the program in such a way that a change in the knowledge base is not propagated throughout the program like a change in a procedural program can be.
+
+
+
+What's Utter Main UseCase?
+===========================
+WRITING EFFECTIVE USE CASES: http://alistair.cockburn.us/get/2465
+
+Problem:
+
+Solution:
+"The programmer should understand what he is doing, that his growing product remains firmly within his intellectual grip" - Dijkstra
+
+Utter offers you the gift of simplicity via an architectural agility that you get from building simple (one fold,), easy(a very near mental leap) microservices;
+this  dominates all other kinds of agility. Good design is about seperating things apart, in the sense that "less is more".
+
+Utter helps you divide up your software project into fun-sized independently deployable microservices.
+
+Utter lets you build fun-sized independently deployable API endpoints.
+
+Reusability\Usability
+====================
+each utter scopes down its microservice be domain-specific, making it fun-sized codebase. that each domain framework used-by\created-for the microservice can be extended via plugins and reused declarativly in another microservice of the same domain.
+
+Mapping a single domain into many mircroservices. but one microservice to focus on one aspect of the domain and customize its domain stack via extneded middlewares.
+
+Encapsulating functinality is not a new idea, but what makes utter stands out is that the developed codebase now is not only reusable, but actually Usable from the prespective of other microservice developers, as they access the functionality declarativly, without worrying about the implmentation details. 
+
+Utter Middleware extensiable architecture makes every compnenet reusable. and Declarative programming makes every component created via Utter highly usable.
+
+
+What is the Domain-specific Microservices Architectural Pattern?
+============================================================
+An architectural pattern is a general, reusable solution to a commonly occurring problem in software architecture within a given context.[1] Architectural patterns are similar to software design pattern but have a broader scope. The architectural patterns address various issues in software engineering, such as computer hardware performance limitations, high availability and minimization of a business risk. Some architectural patterns have been implemented within software frameworks.
+
+When developing a software architecture, we have to consider not only functional requirements, but also non-functional requirements, such as performance, robustness, failure tolerance, throughput, adaptability, extendibility, reusability, and so on. Indeed, one of the purposes of software architectures is to be able to quickly tell how a piece of software satisfies its requirements.
+
+
+What is a Domains-specific Microservice?
+==================================================
+A Domain-specific Mircoservice is a web service responsible to utilize the knowledge of a specific domain. 
+
+How to define the scope of a domain?
+======================================
+Domain scoping is the process that dentifies the domain of interest, the stakeholders and their goals.
+Domain scoping is economically viable and promises success.
+
+
+
+When to extend a domain vs dividing it up into an n number of finer-grained scoped domains?
+=============================================================================================
+Knowledge utilized within an Domain-specific Microservice should only belong to its core domain. If the case arises that supporting domains or other generic domains are identifable, then they should be scoped out into their own domains.
+
+How to extend a domain?
+=======================
+
+
+
+What does Utter consits of under the hood?
+==========================================
+Sinatra
+Mushin
+SSD
+DiskCloud
+
+What is mushin?
+===============
+Building an application often requires the utilization of knowledge from a number of different domains. 
+Domain­specific frameworks are source code artifacts, rather limited to mainstream domains such as web, desktop, and mobile development; 
+and they incorporate knowledge from other domains, via extensions. 
+Mushin argues that a diversity of domain­specific frameworks might positively influence the construction of software applications. 
+Hence Mushin intends to support domain­specific framework developers, via providing a generative approach for building domain­specific frameworks, 
+Hoping that this may aid the convergence towards a diversity of domain­specific frameworks and their corresponding ecosystems.
+
+Utter is a - Simplicity Fuck'n Matters - microservies framework for building fun-sized independently deployable services.
+
+Via using Utter each microservice, you create shall exhibit the following Domain-Driven Design coherences:
+• Complete functionally Resource representation
+• Append-only Data management
+• Each microservice handles one resource (or verb), e.g Clients, Shop Items, Carts, Checkout, etc.
+- minmizes the number of choices of Design Patterns per service.
+
+fully acknowldges the philosphy of ... with the caveats of ...
+
+- seperate reading data from writing data.
+
+Independant
+=============
+- Independent Hires\Outsourcing
+By dividing up your system into Utter services you can safely hire\outsource outsource development for some functionality without the need for them to ever touch your codebase, Simply all they need is the documentation of the APIs they are to interact with. 
+
+- Independent Deployability is key
+It enables separation and independent evolution of
+• code base
+• technology stacks
+• scaling
+• and features, too
+
+- Independent code base
+Each service has its own software repository
+• Codebase is maintainable for developers – it fits into their brain
+• Tools work fast – building, testing, refactoring code takes seconds
+• Service startup only takes seconds
+• No accidental cross-dependencies between code bases
+
+- Independent technology stacks
+Each service is implemented on its own technology stacks
+• The technology stack can be selected to fit the task best
+• Teams can also experiment with new technologies within a single microservice
+• No system-wide standardized technology stack also means
+• No struggle to get your technology introduced to the canon
+• No piggy-pack dependencies to unnecessary technologies or libraries
+• It‘s only your own dependency hell you need to struggle with 
+• Selected technology stacks are often very lightweight
+• A microservice is often just a single process that is started via command line, and not code and
+configuration that is deployed to a container.
+
+- Independent Scaling
+Each microservice can be scaled independently. 
+Identified bottlenecks can be addressed directly.
+Data sharding can be applied to microservices as needed (Utter uses DiskCloud).
+Parts of the system that do not represent bottlenecks can remain simple and un-scaled.
+
+- Independent evolution of Features: 
+Microservices can be extended without affecting other services, 
+For example, you can deploy a new version of (a part of) the UI without re-deploying the whole systemi, 
+You can also go so far as to replace the service by a complete rewrite. But you have to ensure that the service interface remains stable
+
+
+
+ref: http://www.pst.ifi.lmu.de/Lehre/wise-14-15/mse/microservice-architectures.pdf
+
+
+What is Utter?
+==============
+- An utter microservice is an endpoint (a web delivery mechanism) on top of a single domain-based bounded context (mushin domain along with plugins). 
+- Each utter application is a dockerized straightforward-to-test isolated "SINGLE" versioned independently-deployable Endpoint(with an n number of routes) along with a domain bounded-context. 
+- your API documentation acts as the registery of which each team member knows what services are available on which endpoinnds and versions. 
+- you build an endpoint service, you deploy it indepentently, you update the centerilized API docs. and the rest of your team and the world get to start using it.
+- utter gives you fine-tuning for which part of your application needs horizontal scale resources, as your application is really divided up into microserices.
+- utter builds endpoints that logs out with 'Correlation IDs' that helps you to stacktrace errors and visualize how services talk to each other.
+- normally the term “micro” refers to the sizing: a microservice must be manageable by a single development team (5-9
+developers), Utter argues that a service is a single endpoint/single domain (usually managed by a pair of software engineers). Utter belives that this enforced constrain makes you scale down your domain and its endpoint interfaces small enough but not too small.
+- Independent deployability implies no shared state and inter-process communication (often via HTTP REST-ish
+interfaces)
+- Functional system decomposition means vertical slicing
+(in contrast to horizontal slicing through layers)
+- Microservices are fun-sized services, as in
+ “still fun to develop and deploy”
 
-Utter is  microservies framework for building independently deployable services. 
 
 Why Utter
 ==========
 Utter loves sinatra! thats why it is built on top of it, but make smart descions to faciliate the building of microservices.
+Utter doesn't GIVE A RAT ASS about SQL-based backends integrations (IF YOUR OLD SQL TROLLS AREN't DEAD ALREADY, FIRE'M ALL).
 
 Alternative Frameworks
 =======================
 Utter sees Grape as poluted framework.
-Utter sees Rails as MUST-Avoid framework.
+Utter sees Rails as an ALMOST-ALWAYS A MUST-Avoid framework.
+Utter sees the Lotus as NOT focused enough on microservices.
+Utter sees Padrino as Rails wanna-be that provides TOO MANY options! (not microservices specific)
+Utter sees Ramaze, NYNY, Nancy, Cuba, Camping, Crepe, Hobbit, Kenji, Brooklyn as absoulte yet a GOTO to steal some good ideas! 
+As simplicity is a Prequesite for Reliability, IT FUCK'N MATTERS!
+
+Utter Project Structure
+=========================
+- ProjectName::V1::MicroserviceName (`utter new project` asks you about projectname, version, endpoint name i.e gitlapse::v1::lapses)
+ - microservice (a microservice web delivery mechanism (interface) of the application Domain bounded context) - NOTE it is "endpoint" and NOT "endpoints"
+   - lib
+    - lapses_microservice.rb
+   - spec
+    - lapses_microservice_spec.rb
+ - domain (a mushin domain framework, along with its  middlewares - thats the lib and spec of your application) - NOTE it is "domain" and NOT "domains"
+   - lib
+    - lapse.rb (uses mushin framework stack)
+    - middleware_name.rb (middleware plugin)
+    - middleware_name.rb (middleware plugin)
+   - spec
+    - lapses_spec.rb
+ - Dockerfile
+ - Gemfile
+ - Rakefile (for running domain and endpoint tests) (rake is also used for building, and running dockerfile as subtitute for my run.sh)
 
-Example:
-========
+Utter Examples
+===============
+Example: ========
 > utter deploy user@serverip
 1. Uses puma and nginx Dockerfile to create a proxy container and bind it to the host server 
 2. this command makes a packages gem with the following structure for each endpoint and uploads it to the server
@@ -70,10 +304,18 @@ Example:
   ====================
   - Utter deploy command deploys for each endpoint (endpoint gem + Dockerfile, DATA docker-volume for SSD), nginx image for mapping ports and services.
 
-
-
   External Refs:
   - http://martinfowler.com/articles/microservices.html
   - http://highscalability.com/blog/2014/4/8/microservices-not-a-free-lunch.html
 
+What is a Rule-based Microservice (Advanced)
+=============================================
+A rule-based microservice is a service that allows you to send a set of production-rules(facts) that describe what you like the status of your application to be.
+In oppostion a normal microservice would ask you to send primative data which you would normall catch on the backend and mainpulate somehow to make it ready suitable to change the state of your application.
+
+In that sense rule-based microservice allows its clients to interact with it via a "Rule Book". clients read the "Rule Book" and send facts to the microservice, the microservice checks the "Rule book" and updates the status of the application accordingly. And as the microservice is domain-specific so is the Rule Book, meaning the clients can always get an Expert's advice on what the status of the application should be. This makes the Microservice highly usable!
+
+More info is always found on hackspree videos or blogposts at hackspree.com; videos and blogposts are part of active hackspree online workshops to which users can register to fully if they like. Also other contributors who provide consulting services for Utter, Mushin, etc. can edit this wikipage on github to add their corrsponding references as well, by no means this is exclusive to hackspree.
 
+https://www.hackspree.com/microservices-course/whatismicroservices.video
+https://www.hackspree.com/ChainofResponsibilityDesignPattern

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "utter"
+#require "utter"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,8 @@ require "utter"
 # require "pry"
 # Pry.start
 
-require "irb"
-IRB.start
+#require "irb"
+#IRB.start
+require 'pry'
+
+Pry.start

data/bin/scaffold.rb

@@ -0,0 +1,131 @@
+#TODO remove highline and use Thor generators
+# http://whatisthor.com/
+# http://blog.plataformatec.com.br/2009/07/creating-your-own-generators-with-thor/
+
+require 'highline'
+# Basic usage
+
+cli = HighLine.new
+
+
+# project name
+answer = cli.ask "What's your project name?"
+puts "You have answered: #{answer}"
+
+# microservice version
+answer = cli.ask "What's your microservice version?"
+puts "You have answered: #{answer}"
+
+
+cli.choose do |menu|
+  menu.prompt = "What's your miroservice version?"
+  menu.choice(:v1) do 
+    cli.say("confirmed v1") 
+  end
+
+  menu.choices(:v2) do
+    cli.say("confirmed v2") 
+  end
+
+  menu.choices(:v3) do
+    cli.say("confirmed v3") 
+  end
+
+  menu.choices(:v4) do
+    cli.say("confirmed v4") 
+  end
+
+  menu.choices(:v5) do
+    cli.say("confirmed v5") 
+  end
+end
+
+
+
+
+# microservice version
+answer = cli.ask "What's your microservice name?"
+puts "You have answered: #{answer}"
+
+# microservice type 
+#answer = cli.ask "Is your microservice public or private?"
+#puts "You have answered: #{answer}"
+
+
+cli.choose do |menu|
+  menu.prompt = "What's your miroservice type?"
+  menu.choice(:public) do 
+    cli.say("confirmed 'Public' microservice!") 
+  end
+  menu.choices(:private) do
+    cli.say("confirmed 'Private' microservice!") 
+  end
+end
+
+
+
+# microservice deployment 
+#answer = cli.ask "What's your microservice host IP?"
+#puts "You have answered: #{answer}"
+#cli.ask("Enter your host password:  ") { |q| q.echo = "x" }
+
+#cli.choose do |menu|
+#  menu.prompt = "Please choose your favorite programming language?  "
+#  menu.choice(:ruby) { cli.say("Good choice!") }
+#  menu.choices(:python, :perl) { cli.say("Not from around here, are you?") }
+#end
+
+
+=begin
+
+# Default answer
+
+cli.ask("Company?  ") { |q| q.default = "none" }
+
+
+# Validation
+
+cli.ask("Age?  ", Integer) { |q| q.in = 0..105 }
+cli.ask("Name?  (last, first)  ") { |q| q.validate = /\A\w+, ?\w+\Z/ }
+
+
+# Type conversion for answers:
+
+cli.ask("Birthday?  ", Date)
+cli.ask("Interests?  (comma sep list)  ", lambda { |str| str.split(/,\s*/) })
+
+
+# Reading passwords:
+
+cli.ask("Enter your password:  ") { |q| q.echo = false }
+cli.ask("Enter your password:  ") { |q| q.echo = "x" }
+
+
+# ERb based output (with HighLine's ANSI color tools):
+cli.say("This should be <%= color('bold', BOLD) %>!")
+
+
+# Menus:
+
+cli.choose do |menu|
+  menu.prompt = "Please choose your favorite programming language?  "
+  menu.choice(:ruby) { cli.say("Good choice!") }
+  menu.choices(:python, :perl) { cli.say("Not from around here, are you?") }
+  menu.default = :ruby
+end
+
+
+## Using colored indices on Menus
+
+#HighLine::Menu.index_color   = :rgb_77bbff # set default index color
+
+cli.choose do |menu|
+#  menu.index_color  = :rgb_999999      # override default color of index
+                                       # you can also use constants like :blue
+  menu.prompt = "Please choose your favorite programming language?  "
+  menu.choice(:ruby) { cli.say("Good choice!") }
+  menu.choices(:python, :perl) { cli.say("Not from around here, are you?") }
+end
+
+
+=end

data/bin/templates/README.md

@@ -0,0 +1,7 @@
+This directory contains common microservice templates
+- auth microservice template
+- logging microservice template
+- admin microservice template
+
+- User generate a template and specifiy certain attr to customize the template to their own needs.
+- User then use/further developm the generated microservice.

data/lib/internals/core/auth.rb

@@ -0,0 +1,76 @@
+=begin
+#TODO write RDoc
+module Utter
+  module Internals
+    class Auth < Rack::Auth::Basic #TODO digest is better than basic?
+      def call(env)
+	request = Rack::Request.new(env)
+
+	case request.path when '/docs'
+	  @app.call(env)  # skip auth to access documentation
+	else
+	  super           # perform auth
+	  #TODO use json "sinatra/json" here  to ensure all outcoming response are in json
+
+	  #res = Rack::Response.new
+
+	  # This will automatically set the Content-Length header for you
+	  ##res.write "Hello from Rack!"
+
+	  # You can get/set headers with square bracket syntax:
+	  ##res["Content-Type"] = "Content-type: application/json; charset=utf-8"
+
+	  # returns the standard [status, headers, body] array
+	  ##res.finish
+
+	  # You can set and delete cookies
+	  #   res.set_cookie("user_id", 1)
+	  #   res.delete_cookie("user_id"
+	end
+      end
+    end
+
+    # Any class that inherits from Endpoint, may include Utter::Token to add security
+    # token, a token can be used for authenticating a signed-in user or as an API for your system.
+    #
+    # Usage
+    # 
+    # via curl https://api.example.com/v1/endpoint_name -u token_value:
+    # via Browser http://token_value@localhost:4567/
+    # If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer #{token_value}" instead of -u token_value:
+    #
+    # More Info
+    # - https://en.wikipedia.org/wiki/Digest_access_authentication
+    # - https://github.com/rack/rack/blob/master/lib/rack/auth/basic.rb
+    module Secured
+      def self.included(base)
+	base.class_eval do
+
+	  use Auth, "#{self}" do |username, password| 
+
+	    $log.info "username #{username}, password #{username}"
+
+	    if !username.nil? && !password.nil? then
+	      if !User.ssd(username).nil? then
+		if password == User.ssd(username).password then
+		  true # Access Granted
+		else 
+		  false # Access Denied
+		end
+	      end
+	    end
+	  end
+
+	  # 404 Error!
+	  not_found do
+	    status 404
+	    "404 - Check #{self} API documentation"
+	  end
+
+	end
+      end
+    end
+
+  end
+end
+=end

data/lib/internals/core/microservice.rb

@@ -0,0 +1,39 @@
+#TODO write RDoc
+require 'fileutils'
+require 'sinatra'
+require "sinatra/json"
+require 'securerandom'
+require 'sinatra/cross_origin'
+require 'net/http' # Net::HTTP.get('example.com', '/index.html') # => String
+
+module Utter
+  module Internals
+
+    class Microservice < Sinatra::Base
+      # if cross_origin is required\loaded then make register Sinatra::CrossOrigin 
+      # And 
+      #register Sinatra::CrossOrigin
+
+      #TODO 	set a flag to disable this in production for security
+      #		this helps testing APIs on localmachines as CORS fucks developers time.
+      # 		But not recommended to be set while in production enviroments
+      before do
+	response.headers["Access-Control-Allow-Origin"] = "*"
+	response.headers["Access-Control-Allow-Methods"] = "POST"
+	p response.headers.inspect
+      end
+
+      configure { set :server, :puma }
+
+    end
+
+    #class Public::Microservice < Utter::Microservice; end
+
+    #class Private::Microservice < Utter::Microservice
+      #TODO do somthing here to make it secure via some mechanism!
+      # as we don't do websites, we striclty focus on APIs we can use HTTP basic auth to make it secure!?
+
+    #end
+
+  end
+end

data/lib/internals/core/service_discovery.rb

@@ -0,0 +1,2 @@
+# how a client find out which URI::PORT a specific microservice is mounted on
+#TODO check docker gems and docker-compose

data/lib/internals/core/service_registration.rb

@@ -0,0 +1,2 @@
+# how a client registers a specific microservice and mount it on URI::PORT 
+#TODO check docker gems and docker-compose

data/lib/{utter/model.rb → internals/testing/model_delete.rb}

@@ -1,3 +1,4 @@
+#TODO delete as mushin domains wouldn't require utter users to use this model, they should be using a mushin middleware of some kind to store their shit
 #TODO write RDoc
 module Utter
   class Model

data/lib/internals/testing/spec.rb

@@ -0,0 +1,12 @@
+require 'minitest'
+require 'minitest/spec'
+require "minitest/autorun"
+require "minitest/pride"
+
+module Utter
+  module Spec
+    # use it to build specs
+    class Endpoint
+    end
+  end
+end

data/lib/utter.rb

@@ -1,13 +1,68 @@
 require 'logger'
+require 'mushin'
 
-require_relative "utter/version"
-require_relative "utter/store"
-require_relative "utter/model"
-require_relative "utter/endpoint"
-require_relative "utter/auth"
-
+#require_relative "internals/core/store"
+#require_relative "internals/core/auth"
+require_relative "internals/core/microservice"
 
 
+# Utter defines its interfacing points here. Utter communicate seamlessly 
+# via this facade pattern to its internals. This allows all Utter applications 
+# makes it easy to have consistant improvments without updating their codebases.
+#
+#NOTE According to Semantic Versioning 2.0.0 (http://semver.org/); Any changes 
+# to this file would require an upgrade to a new Major version. 
 module Utter
+  # MAJOR version when you make incompatible API changes,
+  # MINOR version when you add functionality in a backwards-compatible manner, and
+  # PATCH version when you make backwards-compatible bug fixes.
+  VERSION = "1.0.9"
+
   $log = Logger.new(STDOUT)
+
+  # Utter choose to provide its functionality via Classes vs Modules as an assertive way of specifing behaviour.
+
+  # Auth is used to build authentication Microservices and is also used utter generated templates.
+  #class Auth < Utter::Internals::Auth; end
+
+  # BASIC FEATURE
+  #TODO configuring an options {} to define if a microservice is public or private
+  # Public::Microservice can be used to provide a microservice that doesn't require authentication.
+  #class Public::Microservice < Utter::Internals::Public::Microservice; end
+  # Private::Microservice can be used to provide a microservice that DOES require authentication.
+  class Microservice < Utter::Internals::Microservice; end
+
+  # BASIC FEATURE
+  # Usage of non domain-specific stack inside a microservice would be like
+  # Stack.new do  
+  #   use Trace,  "A opts hash",  x
+  #   use Trace,  "B opts hash", "B params hash"
+  #   use Trace,  "C opts hash", "C params hash"
+  # end
+  # Very helpful if you just want to build extenstions conforming to Mushin ducking interface of :initialize(app), :call(env)
+  # Yet it is strongly encourged to require your own domain-specific frameworks generated via mushin inexample, and use only
+  # a constraining yourself for a single domain-framework per microservice. example
+  #
+  # require 'domainframeworkXYZ'
+  # require 'domainframeworkXYZ_ext_1'
+  # require 'domainframeworkXYZ_ext_2'
+  # require 'domainframeworkXYZ_ext_3'
+  # DomainFrameworkXYZ::Stack do 
+  #  use DomainFrameworkXYZ_EXT_1, opts, params
+  #  use DomainFrameworkXYZ_EXT_2, opts, params
+  #  use DomainFrameworkXYZ_EXT_3, opts, params
+  # end
+  # this way your work on that domain is ackonwledge\enhanced by the community at large.
+  class Stack < Mushin::Stack
+    # Manipulating the Stack
+    # Implicitly insert storage via SSD ext (NOONE ELSE NEEDS TO KNOW ABOUT SSD, EXCEPT HERE! BEAUTIFUL!!!!!!)
+    # or Explicitly insert it while being in the microservice this way develoeprs get to choose when to use 
+    # the right tool for the job. Example SSD for somthing, and Redis for some Caching microservice, etc.
+  end
+
+  # ADVANCED FEATURE
+  #TODO expose mushin rule-based capabilities via Utter to provide json rule-based microservices
+
+  # Asserts that Utter::Internals namespace is inaccessible directly for Utter apps.
+  private_constant :Internals 
 end

data/samples/README.md

@@ -0,0 +1,3 @@
+maybe uploads microservice is a bad choice! as being rule-based any uploads
+will be part of the rules {} sent as base64. so there should not be any uplaods endpoints or microservice instead
+it should be a plural noun!  like lapses

data/{examples → samples/upjoystream::v1::auth}/config.ru

@@ -8,9 +8,9 @@
 require './app'
 
 map('/public') do
-  run API::V1::PublicEndpoint 
+  run API::V1::Public::Microservice
 end
 
 map('/private') do
-  run API::V1::PrivateEndpoint 
+  run API::V1::Private::Microservice
 end

data/{examples → samples/upjoystream::v1::auth/microservice/lib}/app.rb

@@ -3,7 +3,7 @@ require 'utter'
 
 module API
   module V1
-    class PublicEndpoint < Utter::Endpoint
+    class PublicEndpoint < Utter::Public::Endpoint
       $log.info("mounting #{self}")
       get '/' do
 	"public info"
@@ -11,7 +11,7 @@ module API
       run! if app_file == $0
     end
 
-    class PrivateEndpoint < Utter::Endpoint
+    class PrivateEndpoint < Utter::Private::Endpoint
       $log.info("mounting #{self}")
       get '/' do
 	"private info (eyes only)"

data/samples/upjoystream::v1::torrents/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+ruby '2.3.1'
+
+gem 'utter'

data/samples/upjoystream::v1::torrents/Gemfile.lock

@@ -0,0 +1,34 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    multi_json (1.12.1)
+    rack (1.6.4)
+    rack-protection (1.5.3)
+      rack
+    sinatra (1.4.7)
+      rack (~> 1.5)
+      rack-protection (~> 1.4)
+      tilt (>= 1.3, < 3)
+    sinatra-cross_origin (0.3.2)
+    sinatra-json (0.1.0)
+      multi_json (~> 1.0)
+      sinatra (~> 1.0)
+    ssd (0.1.4)
+    tilt (2.0.5)
+    utter (1.0.5)
+      sinatra
+      sinatra-cross_origin
+      sinatra-json
+      ssd
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  utter
+
+RUBY VERSION
+   ruby 2.3.1p112
+
+BUNDLED WITH
+   1.12.5

data/samples/upjoystream::v1::torrents/config.ru

@@ -0,0 +1,17 @@
+# config.ru (run with rackup)
+##begin
+#  require 'rack/show_exceptions'
+#rescue LoadError
+#  require 'rack/showexceptions'
+#end
+require 'bundler/setup'
+Bundler.require(:default)
+
+require 'utter'
+#require './app'
+Dir[File.dirname(__FILE__) + 'domain/lib/*.rb'].each {|file| require file }
+Dir[File.dirname(__FILE__) + 'microservice/lib/*.rb'].each {|file| require file }
+
+map('/') do
+  run API::V1::Torrents
+end

data/samples/upjoystream::v1::torrents/domain/lib/echo_ext.rb

@@ -0,0 +1,11 @@
+class Echo
+  def initialize(app, message)
+    @app = app
+    @message = message
+  end
+
+  def call(env)
+    puts @message
+    @app.call(env)
+  end
+end

data/samples/upjoystream::v1::torrents/microservice/lib/app.rb

@@ -0,0 +1,14 @@
+#require 'rack/show_exceptions'
+
+module API
+  module V1
+    class Torrents < Utter::Microservice 
+      $log.info("mounting #{self}")
+      get '/' do
+	"public info"
+	"private info (eyes only)"
+      end
+      #run! if app_file == $0
+    end
+  end
+end

data/utter.gemspec

@@ -1,7 +1,7 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'utter/version'
+require_relative 'lib/utter'
 
 Gem::Specification.new do |spec|
   spec.name          = "utter"
@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["zotherstupidguy"]
   spec.email         = ["zotherstupidguy@gmail.com"]
 
-  spec.summary       = %q{Utter is  microservies framework for building independently deployable services.}
-  #  spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.summary       = %q{Utter is a Domain-specific Microservices Framework written in Ruby.}
+  spec.description   = %q{ Utter is a Domain-specific Microservices Framework written in Ruby. Utter helps you divide up your software project into fun-sized independently deployable API endpoints.}
   spec.homepage      = "https://github.com/utter-rb"
   spec.license       = "MIT"
 
@@ -27,9 +27,22 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_development_dependency "pry"
+  spec.add_runtime_dependency "pry"
+
+  spec.add_development_dependency "highline"
+  spec.add_runtime_dependency "highline"
+
+
   spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_runtime_dependency "bundler", "~> 1.12" #TODO use bundler to generate customized Gemfile for Utter generated files
+
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_runtime_dependency "rake", "~> 10.0"
+
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_runtime_dependency "minitest", "~> 5.0"
+
 
   spec.add_development_dependency "sinatra" 
   spec.add_runtime_dependency 'sinatra' 
@@ -40,10 +53,17 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "sinatra-cross_origin" 
   spec.add_runtime_dependency "sinatra-cross_origin"
 
-  spec.add_development_dependency "ssd" 
-  spec.add_runtime_dependency "ssd" 
+  spec.add_development_dependency "ssd"
+  spec.add_runtime_dependency "ssd"
+
+  spec.add_development_dependency "rack-test"
+  spec.add_runtime_dependency "rack-test"
+
+
+  spec.add_development_dependency "puma"
+  spec.add_runtime_dependency "puma"
 
-  spec.add_development_dependency "puma" 
-  spec.add_runtime_dependency "puma" 
+  spec.add_development_dependency "mushin"
+  spec.add_runtime_dependency "mushin"
 
 end

metadata

@@ -1,15 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: utter
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.9
 platform: ruby
 authors:
 - zotherstupidguy
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-15 00:00:00.000000000 Z
+date: 2016-10-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +262,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -192,7 +318,37 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+- !ruby/object:Gem::Dependency
+  name: mushin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mushin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: " Utter is a Domain-specific Microservices Framework written in Ruby.
+  Utter helps you divide up your software project into fun-sized independently deployable
+  API endpoints."
 email:
 - zotherstupidguy@gmail.com
 executables: []
@@ -207,17 +363,27 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/scaffold.rb
 - bin/setup
-- examples/Gemfile
-- examples/Gemfile.lock
-- examples/app.rb
-- examples/config.ru
+- bin/templates/README.md
+- lib/internals/core/auth.rb
+- lib/internals/core/microservice.rb
+- lib/internals/core/service_discovery.rb
+- lib/internals/core/service_registration.rb
+- lib/internals/core/store.rb
+- lib/internals/testing/model_delete.rb
+- lib/internals/testing/spec.rb
 - lib/utter.rb
-- lib/utter/auth.rb
-- lib/utter/endpoint.rb
-- lib/utter/model.rb
-- lib/utter/store.rb
-- lib/utter/version.rb
+- samples/README.md
+- samples/upjoystream::v1::auth/Gemfile
+- samples/upjoystream::v1::auth/Gemfile.lock
+- samples/upjoystream::v1::auth/config.ru
+- samples/upjoystream::v1::auth/microservice/lib/app.rb
+- samples/upjoystream::v1::torrents/Gemfile
+- samples/upjoystream::v1::torrents/Gemfile.lock
+- samples/upjoystream::v1::torrents/config.ru
+- samples/upjoystream::v1::torrents/domain/lib/echo_ext.rb
+- samples/upjoystream::v1::torrents/microservice/lib/app.rb
 - utter.gemspec
 homepage: https://github.com/utter-rb
 licenses:
@@ -239,8 +405,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.7
 signing_key: 
 specification_version: 4
-summary: Utter is  microservies framework for building independently deployable services.
+summary: Utter is a Domain-specific Microservices Framework written in Ruby.
 test_files: []

data/lib/utter/auth.rb

@@ -1,74 +0,0 @@
-#TODO write RDoc
-module Utter
-
-  class Auth < Rack::Auth::Basic
-    def call(env)
-      request = Rack::Request.new(env)
-
-      case request.path when '/docs'
-	@app.call(env)  # skip auth to access documentation
-      else
-	super           # perform auth
-	#TODO use json "sinatra/json" here  to ensure all outcoming response are in json
-
-	#res = Rack::Response.new
-
-	# This will automatically set the Content-Length header for you
-	##res.write "Hello from Rack!"
-
-	# You can get/set headers with square bracket syntax:
-	##res["Content-Type"] = "Content-type: application/json; charset=utf-8"
-
-	# returns the standard [status, headers, body] array
-	##res.finish
-
-	# You can set and delete cookies
-	#   res.set_cookie("user_id", 1)
-	#   res.delete_cookie("user_id"
-      end
-    end
-  end
-
-
-  # Any class that inherits from Endpoint, may include Utter::Token to add security
-  # token, a token can be used for authenticating a signed-in user or as an API for your system.
-  #
-  # Usage
-  # 
-  # via curl https://api.example.com/v1/endpoint_name -u token_value:
-  # via Browser http://token_value@localhost:4567/
-  # If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer #{token_value}" instead of -u token_value:
-  #
-  # More Info
-  # - https://en.wikipedia.org/wiki/Digest_access_authentication
-  # - https://github.com/rack/rack/blob/master/lib/rack/auth/basic.rb
-  module Secured
-    def self.included(base)
-      base.class_eval do
-
-	use Auth, "#{self}" do |username, password| 
-
-	  $log.info "username #{username}, password #{username}"
-
-	  if !username.nil? && !password.nil? then
-	    if !User.ssd(username).nil? then
-	      if password == User.ssd(username).password then
-		true # Access Granted
-	      else 
-		false # Access Denied
-	      end
-	    end
-	  end
-	end
-
-	# 404 Error!
-	not_found do
-	  status 404
-	  "404 - Check #{self} API documentation"
-	end
-
-      end
-    end
-  end
-
-end

data/lib/utter/endpoint.rb

@@ -1,27 +0,0 @@
-#TODO write RDoc
-require 'fileutils'
-require 'sinatra'
-require "sinatra/json"
-require 'securerandom'
-require 'sinatra/cross_origin'
-require 'net/http' # Net::HTTP.get('example.com', '/index.html') # => String
-
-module Utter
-  class Endpoint < Sinatra::Base
-    # if cross_origin is required\loaded then make register Sinatra::CrossOrigin 
-    # And 
-    #register Sinatra::CrossOrigin
-
-    #TODO 	set a flag to disable this in production for security
-    #		this helps testing APIs on localmachines as CORS fucks developers time.
-    # 		But not recommended to be set while in production enviroments
-    before do
-      response.headers["Access-Control-Allow-Origin"] = "*"
-      response.headers["Access-Control-Allow-Methods"] = "POST"
-      p response.headers.inspect
-    end
-
-    configure { set :server, :puma }
-
-  end
-end

data/lib/utter/version.rb

@@ -1,3 +0,0 @@
-module Utter
-  VERSION = "1.0.6"
-end