fabrique 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4daf727bd88f8eb4d46c304c084da967dbb73a0c
-  data.tar.gz: 2bb4305c3529851cf01d62c8a31ec7e0999df500
+  metadata.gz: 8683ae625b53e11ecf2abd341320e42a060906fc
+  data.tar.gz: 34b2ae0dc2fb5aa5b8436ab1b275e19f388a9484
 SHA512:
-  metadata.gz: f39eca63286eca501f0b5a0521f782e9573105508e2e28bc9f85bcdfa78586858e4114088c893fb98228ad46ed771c653d15c3a7fc589c283513e29fff77dcd1
-  data.tar.gz: b3dda7ca00ff149cd4d76ce07b725b9fc0603882d21fd5ccd6f3c5ae44beed65e2b85e0d8edffa5d82c5d97abf36e730912b76ee481e99582d38b4ba17b67a37
+  metadata.gz: ebaa94d196dde76335b23b3d5b78212d9d71d41cced7c950479561c8ea5a0ea85c59c069dfa1478dbe34a3a17bf1b61ade882d2c357b2d183c05ad03836d30c4
+  data.tar.gz: 326909d817f1a2ba15e8363fe21e74e5c5419ce199306b5bda2609eb3a34bc485120661c2895b99100abd37c43271ddc03fd9773dad12a68f55378ca604a356a

data/.travis.yml

@@ -1,3 +1,6 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 2.1.5
+  - 2.2.1
+bundler_args: --without devtools

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in fabrique.gemspec
 gemspec
+
+group :devtools do
+  gem "guard-cucumber", "~> 1.5"
+  gem "byebug", "~> 3.5"
+end

data/Guardfile

@@ -0,0 +1,9 @@
+guard "cucumber" do
+  watch(%r{^lib/.+\.rb$})
+  watch(%r{^features/.+\.feature$})
+  watch(%r{^features/support/.+$})          { "features" }
+
+  watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "features"
+  end
+end

data/README.md

@@ -1,6 +1,8 @@
+[![Gem Version](https://badge.fury.io/rb/fabrique.svg)](http://badge.fury.io/rb/fabrique) [![Build Status](https://travis-ci.org/starjuice/fabrique.svg?branch=master)](https://travis-ci.org/starjuice/fabrique) [![Dependency Status](https://gemnasium.com/starjuice/fabrique.svg)](https://gemnasium.com/starjuice/fabrique)
+
 # Fabrique
 
-TODO: Write a gem description
+Factory support library for adapting existing modules for injection as dependencies.
 
 ## Installation
 
@@ -20,11 +22,158 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Under construction; hard hat required!
+
+## Puzzling
+
+However plugin factories are composed, the process of constructing a plugin
+will be:
+
+```ruby
+Properties -> PropertyValidator -> ArgumentAdaptor -> Constructor => plugin`
+```
+
+A global function that takes the plugin registration as the composite would
+then look like this:
+
+```ruby
+def fabricate(registry, plugin_identity, properties)
+  registration = registry.find(plugin_identity)
+  property_validator = registration.property_validator
+  argument_adaptor = registration.argument_adaptor
+  constructor = registration.constructor
+  plugin_template = registration.template # Currently called the type
+
+  if property_validator.valid?(properties)
+    arguments = argument_adaptor.adapt(properties)
+    plugin = constructor.construct(plugin_template, arguments)
+    return plugin
+  else
+    raise
+  end
+end
+```
+
+So we might compose thus:
+
+```ruby
+# API gem does this
+class Store
+  def initialize(provider)
+    @provider = provider
+  end
+  # API definition
+end
+StoreApiFactory = Fabrique::FactoryAdaptor.new(
+  template: Store,
+  constructor: Constructor::Classical.new,
+  argument_adaptor: ArgumentAdaptor::Positional.new(:provider)
+)
+StoreProviderFactoryRegistry = Fabrique::Registry.new("Store API Provider Registry")
+
+# Provider gem does this
+require "store_api"
+class S3StoreProvider
+  # API implementation here
+end
+S3StoreProviderFactory = Fabrique::FactoryAdaptor.new(
+  template: S3StoreProvider,
+  constructor: Constructor::Classical.new,
+  argument_adaptor: ArgumentAdaptor::Keyword.new,
+)
+StoreProviderFactoryRegistry.register(:s3, S3StoreProviderFactory)
+
+# API consumer does this
+Bundler.require(:default)
+provider_factory = StoreProviderFactoryRegistry.find(:s3)
+provider = provider_factory.create(region: "eu-west-1", bucket: "fabrique")
+api = StoreApiFactory.create(provider: provider)
+
+# Now, if the API consumer and the API developer agree that this is too high ceremony...
+
+# API gem adds this
+class StoreFactory
+  def self.create(provider_id: DEFAULT_PROVIDER, provider_properties: DEFAULT_PROVIDER_PROPERTIES)
+    provider_factory = StoreProviderFactoryRegistry.find(provider_id)
+    provider = provider_factory.create(provider_properties)
+    StoreApiFactory.create(provider: provider)
+  end
+end
+
+# and API consumer just does this
+Bundler.require(:default)
+api = StoreFactory.create(provider_id: :s3, provider_properties: {region: "eu-west-1", bucket: "fabrique"})
+```
+
+Fabrique might be able to offer an easy way to build the low ceremony "provider
+API factory". Let's wait and see if high ceremony is really a problem for people.
+
+### Constructors
+
+What kinds of construction process do we care about?
+
+#### Identity
+
+* Makes no sense to use an ArgumentAdaptor (or, by implication, a
+  PropertyValidator).
+
+So this is a good pressure to compose everything except Properties
+into the Constructor, registered by plugin\_identity.
+
+#### Classical
+
+* Keywords
+* Positional
+* Builder?
+
+If we say you can mix Classical constructor with Builder ArgumentAdaptor,
+then the constructor must call a default constructor only (::new()), passing
+in a block.
+
+#### Builder
+
+If we say Builder is a constructor, then it can pass adapted arguments *and*
+a block to the adapted constructor.
+
+So, does the world really have constructors that take arguments *and* a
+builder block?
+
+#### Lambda?
+
+This could be used to allow *any* adaptation conceivably supported by the
+interface of the provider type.
+
+So, are there adaptations we might want that wouldn't be supported by
+Identity, Classical and Builder? Yes, surely. But are they *factory*
+adaptations? Well...
+
+```ruby
+class BadlyDesigned
+  def initialize(first_name, last_name)
+    @first_name, @last_name = first_name, last_name
+  end
+
+  def set_title(title)
+    @title = title
+  end
+
+  def address
+    "#{@name} #{@first_name} #{@last_name}"
+  end
+end
+
+lambda_constructor = ->(type, properties) do
+  type.new(properties).tap { |o| o.set_title(properties[:title]) if properties.include?(:title) }
+end
+```
+
+But are we in the business of adapting badly designed software for use in
+plugin factories? Should the scope perhaps be to adapt well designed software
+for use in plugin factories?
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/fabrique/fork )
+1. Fork it ( https://github.com/starjuice/fabrique/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -1,7 +1,15 @@
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+begin
+  require "rspec/core/rake_task"
+  require "cucumber"
+  require "cucumber/rake/task"
 
-task :default => :spec
+  RSpec::Core::RakeTask.new(:spec)
 
+  Cucumber::Rake::Task.new(:features) do |t|
+    t.cucumber_opts = "features --format pretty"
+  end
+
+  task :default => [:spec, :features]
+end

data/config/cucumber.yml

@@ -0,0 +1,2 @@
+---
+default: --no-source

data/constructors

@@ -0,0 +1,70 @@
+Properties -> PropertyValidator -> ArgumentAdaptor -> Constructor => o
+
+def fabricate(registry, plugin_identity, properties)
+  registration = registry.find(plugin_identity)
+  property_validator = registration.property_validator
+  argument_adaptor = registration.argument_adaptor
+  constructor = registration.constructor
+  plugin_template = registration.template
+
+  if property_validator.valid?(properties)
+    arguments = argument_adaptor.adapt(properties)
+    plugin = constructor.construct(plugin_template, arguments)
+    return plugin
+  else
+    raise
+  end
+end
+
+Identity
+
+	* Makes no sense to use an ArgumentAdaptor (or, by implication, a
+	  PropertyValidator).
+
+	  So this is a good pressure to compose everything except Properties
+	  into the Constructor, registered by plugin_identity.
+
+Classical
+
+	* Keywords
+	* Positional
+	* Builder?
+
+	  If we say you can mix Classical constructor with Builder ArgumentAdaptor,
+	  then the constructor must call a default constructor only (::new()), passing
+	  in a block.
+
+Builder
+
+	  If we say Builder is a constructor, then it can pass adapted arguments *and*
+	  a block to the adapted constructor.
+
+	  So, does the world really have constructors that take arguments *and* a
+	  builder block?
+
+Lambda?
+
+	  This could be used to allow *any* adaptation conceivably supported by the
+	  interface of the provider type.
+
+	  So, are there adaptations we might want that wouldn't be supported by
+	  Identity, Classical and Builder? Yes, surely. But are they *factory*
+	  adaptations? Well...
+
+	  class BadlyDesigned
+	    def initialize(first_name, last_name)
+	      @first_name, @last_name = first_name, last_name
+	    end
+
+	    def set_title(title)
+	      @title = title
+	    end
+
+	    def address
+	      "#{@name} #{@first_name} #{@last_name}"
+	    end
+	  end
+
+	  lambda_constructor = ->(type, properties) do
+	    type.new(properties).tap { |o| o.set_title(properties[:title]) if properties.include?(:title) }
+	  end

data/docs/autowiring.yml

@@ -0,0 +1,23 @@
+---
+beans:
+  invoice_service:
+    class: InvoiceService
+    method: constructor
+    arguments:
+      - bean:billing_provider
+      - bean:asset_provider
+      - dry_run: true
+  billing_provider:
+    class: FreshBooksBillingProvider
+    method: constructor
+    arguments:
+      - url: https://fb.localdomain/ep
+        license_key: 497bca6b-50192c4c-8384f347-4a3ea754-082a7d70-45e041e2-9cfe07a1-3544d7e5
+  asset_provider:
+    class: AssetPointAssetProvider
+    method: constructor
+    arguments:
+      host: 192.168.22.42
+      port: 443
+      username: user
+      password: secret

data/docs/multiple_providers.rb

@@ -0,0 +1,104 @@
+# Stretch the design to support multiple providers
+
+# The API gem does this
+class InvoiceService
+  def initialize(billing_provider, asset_provider, options = {})
+    @billing_provider, @asset_provider, @options = billing_provider, asset_provider, options
+  end
+
+  def business_method
+    @asset_provider.get_all_assets.map do |asset|
+      @billing_provider.get_billing_for_asset(asset).tap do |billing|
+        if !@options[:dry_run]
+          @billing_provider.invoice_billing(billing)
+        end
+      end
+    end
+  end
+end
+InvoiceServiceApiFactory = Fabrique::FactoryAdaptor::Method.new(
+  template: InvoiceService,
+  method: :new,
+  arguments: Fabrique::ArgumentAdaptor::Positional.new(:billing_provider, :asset_provider, [:properties])
+)
+InvoiceServiceProviderFactoryRegistry = Fabrique::Registry.new(name: "Invoice service billing provider registry", index_components: 2)
+
+# A billing provider gem does this
+require "invoice_service"
+class FreshBooksBillingProvider
+  def initialize(options = {})
+    #...
+  end
+
+  def get_billing_for_asset(asset)
+    {
+      asset: asset,
+      #...
+    }
+  end
+
+  def invoice_billing(billing)
+    #...
+  end
+end
+FreshBooksBillingProviderFactory = Fabrique::FactoryAdaptor::Method.new(
+  template: FreshBooksBillingProvider,
+  method: :new,
+  arguments: Fabrique::ArgumentAdaptor::Keyword.new
+)
+InvoiceServiceProviderFactoryRegistry.register("billing", "freshbooks", FreshBooksBillingProviderFactory)
+
+# An asset provider gem does this
+require "invoice_service"
+class AssetPointAssetProvider
+  def initialize(host: nil, port: nil, username: nil, password: nil)
+    #...
+  end
+
+  def get_all_assets
+    [
+      #...
+    ]
+  end
+end
+AssetPointAssetProviderFactory = Fabrique::FactoryAdaptor::Method.new(
+  template: AssetPointAssetProviderFactory,
+  method: :new,
+  arguments: Fabrique::ArgumentAdaptor::Keyword.new(:host, :port, :username, :password)
+)
+InvoiceServiceProviderFactoryRegistry.register("asset", "assetpoint", AssetPointAssetProviderFactory)
+
+# API consumer does this
+Bundler.require(:default)
+api = InvoiceServiceApiFactory.create(
+  billing_provider: InvoiceServiceProviderFactoryRegistry.find("billing", config.get_string("billing_provider")).create(
+    config.get_properties("billing_provider_properties")
+  ),
+  asset_provider: InvoiceServiceProviderFactoryRegistry.find("asset", config.get_string("asset_provider")).create(
+    config.get_properties("asset_provider_properties")
+  )
+  properties: {dry_run: true}
+)
+
+# Now, if the API consumer and the API developer agree that this is too high ceremony...
+
+# API gem adds this
+InvoiceServiceFactory = Fabrique::Factory::PluggableApi.new(
+  api_factory: InvoiceServiceApiFactory,
+  providers: {
+    billing_provider: {registry: InvoiceServiceProviderFactoryRegistry, index_prefix: ["billing"]},
+    asset_provider: {registry: InvoiceServiceProviderFactoryRegistry, index_prefix: ["asset"]},
+  }
+)
+
+# and API consumer just does this
+Bundler.require(:default)
+api = InvoiceServiceFactory.create(
+  billing_provider: config.get_string("billing_provider"),
+  billing_provider_properties: config.get_string("billing_provider_properties"),
+  asset_provider: config.get_string("asset_provider"),
+  asset_provider_properties: config.get_string("asset_provider_properties"),
+  properties: {dry_run: true}
+)
+
+# Hmmm. That certainly doesn't pay for itself! Screw it, let's just implement Spring Beans for Ruby.

data/fabrique.gemspec

@@ -12,12 +12,15 @@ Gem::Specification.new do |spec|
   spec.description   = %q{Factory support library for adapting existing modules for injection as dependencies}
   spec.homepage      = "https://github.com/starjuice/fabrique"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.0"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "liquid", "~> 3.0"
+
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.2"