stargate 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 29a29b4893f36ea1c2b1da2977aedfa953b5e681
+  data.tar.gz: b6474307574fee4378d27268273c9360855a6e71
+SHA512:
+  metadata.gz: 7f87bd0790583a14ca6f4c288c582a5e3ba718fd248e7372912c378378cdcfc59fedb07ec70f2767ac235aa3999d0097b4abb0ecc1640784334d6348bc25dfc3
+  data.tar.gz: c6862c8cbbec7e54109d34a556ab0404b1f2e82c64b45136a005c13afe242cadd2d8dfdcb7a9e848a6e299277b8e13d035b0628dcb7cd2c1e210bb7beda985f1

data/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+
+...
+
+## [0.1.1]
+
+### Added
+
+- Proof of concept of server and client communication with local injections.

data/Dockerfile

@@ -0,0 +1,11 @@
+FROM ruby:2.2
+
+ENV GEM_NAME stargate
+ENV WORKDIR /usr/local/src/$GEM_NAME
+
+RUN mkdir -p $WORKDIR
+WORKDIR $WORKDIR
+ADD . $WORKDIR
+RUN bundle install
+
+CMD bundle exec rake test

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stargate.gemspec
+gemspec

data/README.md

@@ -0,0 +1,240 @@
+# Stargate
+
+[![Status](https://codeship.com/projects/XXX/status?branch=master)](https://codeship.com/projects/XXX)
+
+Stargate is a portal between ruby (and in the future not any) apps. It facilitates creating internal micro-services
+and allows to scale your logic pretty much infinitely.
+
+## Motivation & Foreword
+
+Writing micro-services comes with huge overhead and problems on all ends:
+
+* Services often speak pseudo REST interfaces, too complex and too troublesome.
+* Consumers need client libraries that are either generated boilerplate code or crated libraries that break more often then they actually work.
+* Testing on both ends is complicated and not really accurate. Often you still have to test your client libs too. Sometimes even generators that create your client libraries must be tested.
+* Client libraries add layer of abstraction that's completely unnecessary and introduces confusion. Different services speak through different REST "practices". The HTTP verbs and headers holy war keeps going, no peace.
+
+IMHO simple RPC services are hero solving this problems. They come with different ones, though, JSON-RPC being the best example.
+
+Here are key objectives I took for this project:
+
+* Simple protocol and exchange format for the start: HTTP + JSON. Minimum effort.
+* Replaceable protocols and exchange formats in the long run.
+* Server versioning out of the box.
+* No REST practices.
+* Client code meta-generated from server definitions. One client for all.
+* Client forced to respect the versioning system.
+* Easy for testing.
+
+Finally, the main objective to call remote methods and obtain remote data just as you would call the method locally. Real key for me was to create a system where it doesn't matter if method or
+class are executed locally or remotely. Fire, get results, forget. No thinking of what's under the hood. The essence of distributed computing without affecting principles of our programming language.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stargate', '0.1.1'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stargate --version 0.1.1
+
+## Usage
+
+1. Define your service:
+
+    ```ruby
+    module NightsWatch
+      class NewBrother
+        def self.oath
+          "I pledge my life and honor to the Night's Watch, for this night and all the nights to come."
+        end
+
+        def self.call(name)
+          Brother.new(name)
+        end
+      end
+
+      class Brother
+        attr_accessor :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def knowledge
+          if name == "Jon Snow"
+            "nothing"
+          else
+            "something"
+          end
+        end
+      end
+    end
+    ```
+
+  Plain ruby object. Class methods are your entry points.
+
+  **NOTE**: Class method should return either basic type (`String`, `Numeric`, `Float`, `TrueClass`, `FalseClass`, `NilClass`), `Hash` of basic types, object of our class or `Array` of basics or such objects. That's first restriction - if you ask me I already write compliant code like this for years.
+
+2. Put it on the wire! Add `config.ru` like this one:
+
+    ```ruby
+    require 'stargate/server'
+    require 'stargate/server/transport/sinatra'
+
+    class NightsWatch
+      # *snip*
+    end
+
+    registry = Stargate::Server::Registry.new do
+      version 1 do
+        serve NightsWatch::NewBrother do
+          class_methods :call, :oath
+        end
+
+        serve NightsWatch::Brother do
+          class_methods :create, :update
+          attributes :name
+          readers :knowledge
+        end
+      end
+    end
+
+    run Stargate::Server::Transport::Sinatra.new(registry)
+    ```
+
+  Entry points are our class methods that shall be exposed over the network. They are remotely callable. The `accessors` are simple all assessor attributes that should be exposed in case of returning object of that class. Finally `readers` are read only attributes. Final note, the `as` option of `serve` block defines exposed name of the class.
+
+  **NOTE**: Here comes second restriction. You can expose only class methods to be callable. Instances are simply treated as data structures. If you expose message, it's result will be cached at the moment of serialization and only result passed over the wire. How do I call instance methods then? You don't.
+
+  Q: So how can I call `ActiveRecord::Base#save` on model object?
+  A: Forget model objects, what you get is eventually a data structure. The structure is remotely stateless.
+  Q: What does it mean "remotely stateless"?
+  A: It means that you can make local changes to the object, but persistence of those changes must go through a service, either local or remote. Persistence methods like `#save` should be called only at the end of the food chain, in the
+  final service.
+  Q: Show me an example?
+
+  ```ruby
+  class Book < ActiveRecord::Base
+    # *snip*
+  end
+
+  class CreateBook
+    def self.call(book)
+      unless book.valid?
+        raise "Uups, the book info is not complete!"
+      end
+
+      book.save
+    end
+  end
+  ```
+
+  Q: What? It looks like Rails controller. Why I can't just call save directly?
+  A: Don't think in the space of operations. Think in processes and define them clearly. Yes it's extra code initially.
+  No it's not a boilerplate. This way you can easily test, mock and track your business processes.
+
+3. Set up your client code:
+
+    ```ruby
+    require 'stargate/client'
+
+    module NightsWatch
+    end
+
+    require_remote 'http+json://localhost:9292/v1'
+
+    class NightsWatch::Brother
+      def knowledge_description
+        "#{name} knows #{knowledge}"
+      end
+
+      def hello
+        "Hello, I'm #{name}!"
+      end
+    end
+
+    jon = NightsWatch::NewBrother.call('Jon Snow')
+    puts jon.hello
+    puts jon.knowledge_description
+    puts jon.class.name
+    puts '----'
+
+    sam = NightsWatch::NewBrother.call('Samwell Tarly')
+    puts sam.knowledge_description
+    puts '----'
+
+    puts NightsWatch::NewBrother.oath
+    ```
+
+  As you can see, single client handles everything. Also the way you connect to remote service is pretty much like requiring any other file or library. Client automatically fetches definitions of exposed classes from remote location (this is done once and can be easily cached for the eventuality of service downtime) and injects all registered classes into global namespace. Now injected classes behave pretty much like they'd be defined locally, with the only exception that under the hood they call remote API to execute stuff and obtain results. As you can also see in `NightsWatch::Brother` proxy class, we can easily extend these classes with plain ruby code.
+
+  **NOTE**: One probably unsupported or at least troublesome thing at the moment is inheritance from the proxy class.
+
+That's it! The services are stateless and can be trivially load balanced or put behind the proxy. The client is one and only and doesn't require you to write more than few lines of code. No custom stuff to learn or define before making use of remote services.
+
+Check `examples` directory to try these examples out.
+
+### Under the hood
+
+The mechanism is uber simple. Expose two endpoints (with whatever protocol you prefer) on the server side without affecting original code. In case of HTTP transport that would be:
+
+```
+GET  /v{version}/definitions.json
+POST /v{version}/{klass_name}.{method}
+```
+
+First returns JSON (or however encoded) definitions of exposed classes. Later is an entry point for calling class methods of exposed classes. It takes encoded arguments as POST request body.
+
+That's it for the server!
+
+Now the client at `require_remote` time fetches definitions and injects configured classes inheriting from `Stargate::Client::Proxy`. All exposed methods are defined dynamically and they pass through to remote calls.
+
+## Development
+
+You have two options to work with this project. The [docker flow](#setup-with-docker) is suggested since solves problems of compatibility of tools.
+
+### Manual Setup
+
+First off, make sure you have **Ruby 2.2+** and latest version of **Bundler** on your machine. After checking out the repo, you can install dependencies and prepare the project with:
+
+    $ bin/setup
+
+Now you can run tests:
+
+    $ bundle exec rake spec
+
+You can also connect to interactive prompt that will allow you to experiment. To do this, run:
+
+    $ bundle exec bin/console
+
+To install this gem onto your local machine, run:
+
+    $ bundle exec rake install
+
+### Setup with Docker
+
+If you're lazy and don't wanna get into how the setup works, here's something for you. This project comes fully [dockerized](http://docker.io/). Install docker toolchain and then go for:
+
+    $ docker-compose build
+
+All done, you can do testing and fiddling around:
+
+    $ docker-compose run facebook_integration bash
+    root@xyyyyxx:/usr/local/src/rake-bump# bundle exec rake spec
+    root@xyyyyxx:/usr/local/src/rake-bump# bundle exec bin/console
+
+### Releasing
+
+TODO: Add link to rake-bump release instructions...
+
+## Contributing
+
+Bug reports and pull requests are welcome [here](https://github.com/jobandtalent/stargate/issues).

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler/gem_tasks"
+require "rake/bump/tasks"
+require "rake/testtask"
+require "stargate/version"
+
+Rake::Bump::Tasks.new do |t|
+  t.gem_name = 'stargate'
+  t.gem_current_version = Stargate::VERSION
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "stargate"
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docker-compose.yml

@@ -0,0 +1,4 @@
+stargate:
+  build: .
+  volumes:
+    - .:/usr/local/src/stargate:rw

data/examples/client/client.rb

@@ -0,0 +1,27 @@
+require 'stargate/client'
+
+ENV['NIGHTS_WATCH_URL'] ||= 'http+json://localhost:9292/v1'
+
+require_remote ENV['NIGHTS_WATCH_URL']
+
+class NightsWatch::Brother
+  def knowledge_description
+    "#{name} knows #{knowledge}"
+  end
+
+  def hello
+    "Hello, I'm #{name}!"
+  end
+end
+
+jon = NightsWatch::NewBrother.call('Jon Snow')
+puts jon.hello
+puts jon.knowledge_description
+puts jon.class.name
+puts '----'
+
+sam = NightsWatch::NewBrother.call('Samwell Tarly')
+puts sam.knowledge_description
+puts '----'
+
+puts NightsWatch::NewBrother.oath

data/examples/server/config.ru

@@ -0,0 +1,45 @@
+require 'stargate/server/engine/sinatra'
+
+module NightsWatch
+  class NewBrother
+    def self.oath
+      "I pledge my life and honor to the Night's Watch, for this night and all the nights to come."
+    end
+
+    def self.call(name)
+      Brother.new(name)
+    end
+  end
+
+  class Brother
+    attr_accessor :name
+
+    def initialize(name)
+      @name = name
+    end
+
+    def knowledge
+      if name == "Jon Snow"
+        "nothing"
+      else
+        "something"
+      end
+    end
+  end
+end
+
+registry = Stargate::Server::Registry.new do
+  version 1 do
+    serve NightsWatch::NewBrother do
+      class_methods :call, :oath
+    end
+
+    serve NightsWatch::Brother do
+      class_methods :create, :update
+      attributes :name
+      readers :knowledge
+    end
+  end
+end
+
+run Stargate::Server::Engine::Sinatra.new(registry)

data/examples/server/start

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -eu
+
+WORKING_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+bundle exec puma -p 9292 --dir $WORKING_DIR $WORKING_DIR/config.ru

data/lib/stargate.rb

@@ -0,0 +1,28 @@
+require 'json'
+require 'gallus'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/module'
+require 'active_support/core_ext/string/inflections'
+
+module Stargate
+  include Gallus::PackageLogging
+
+  # Logging proxy, just in case someday you'd like to switch to different logging lib.
+  Logging = Gallus::Logging
+
+  # Public: Base error.
+  Error = Class.new(StandardError)
+
+  # In-process registry.
+  INPROC = {}
+
+  # Configure logging defaults.
+  ENV['STARGATE_LOG_LEVEL'] = 'DEBUG' if ENV['DEBUG'].to_i > 0
+  log.level = ENV.fetch('STARGATE_LOG_LEVEL', 'INFO')
+
+  require 'stargate/version'
+  require 'stargate/serialization'
+  require 'stargate/codec'
+  require 'stargate/marshal'
+  require 'stargate/metadata'
+end