expose_db 0.1.1 → 0.2.0

data/README.md

@@ -9,8 +9,19 @@ WARNING: ExposeDB doesn't offer any secure options, and as such is expected
          to be used only in a high-trust network!
 
 
-Usage
------
+ExposeDB consists of both a client and server in one package. The server need
+not be used with the client: it simply provides a JSON endpoint. The client
+will wrap that JSON endpoint in a very simple [Sequel][sequel]-like API.
+
+
+But Why?
+--------
+Ideally, connecting straight to the source database would always be possible.
+Since it's not: why.
+
+
+Server Usage
+------------
 ExposeDB is in a very alpha stage of development, but seems to be doing a
 rudimentary job querying for data. Output options are currently limited to
 *all* fields in a table and is only exposed via JSON.
@@ -27,12 +38,97 @@ Existing endpoints:
 * `/my_table?q=ENCODED_QUERY&values[]=2&values[]=bob` - replace ?'s in ENCODED_QUERY with [2, 'bob']
 
 
+Client Usage
+------------
+ExposeDB client use isn't required to use the server, but provides a very simple
+mapping layer built with [Hashie][hashie]. Use `exposed_as` to define the server's
+table name after inheriting from `ExposeDB::Model` and setting your subclass's
+`base_uri`. You can `find` and `filter` your models, along with anything that
+[HTTParty][httparty] provides.
+
+Since the models are built from a `Hashie::Mash`, you don't need to define
+any fields or columns on the client side.
+
+```ruby
+require 'expose_db/model'
+
+class BaseModel < ExposeDB::Model
+  base_uri 'http://api.example.com/v1'
+end
+
+class Person < BaseModel
+  exposed_as 'people'
+
+  # Class is inferred from singular of relation name, and foreign key is assumed
+  # to be this_class_name_id. Singular inflections are very limited, so you may
+  # need to specify class_name here
+  has_many :tasks
+end
+
+class Task < BaseModel
+  exposed_as 'tasks'
+
+  # Assume the returned task has a person_id column and the class_name is Person
+  belongs_to :person
+
+  # Provie a wrapper for the underlying string from the ExposeDB server
+  def completed_at
+    ca = self[:completed_at]
+    ca ? Time.parse(ca) : nil
+  end
+end
+
+bob = Person.find(123)
+#=> your person (by column `id`) or raise ExposeDB::RecordNotFound
+
+bob.tasks
+#=> find all tasks with person_id = 123
+
+Person.find_by_id(123)
+#=> your person (by column `id`) or nil
+
+Person.filter('last_name = ? AND first_name LIKE ?',
+              "Saget", "B%")
+#=> array of persons with last_name of Saget and first_name starting with B
+
+Task.find(456).person.first_name
+#=> Load task with `id` 456, then request Person with `id` (if task.person_id isn't nil)
+#   This task's person is cached on the task itself, but there is no identity map
+#   so all Task.find(456) calls will call the server again.
+```
+
+Implementing your own filter methods are easy:
+```ruby
+class Task < BaseModel
+  exposed_as 'tasks'
+
+  # Assume the returned task has a person_id column and the class_name is Person
+  belongs_to :person
+
+  def self.completed_for_person(person)
+    filter('person_id = ? AND completed = 1', person.id)
+  end
+
+  def self.next_for_person(person)
+    # NOTE: Currently, this pulls back ALL the items maching the query and only
+    #       then selects the first task
+    filter('person_id = ? AND completed = 0', person.id).first
+  end
+end
+```
+
+
 TODO
 ----
 * Tests
+* Smarter relations
+  * Has one
+  * Offsets and limits
+* Other missing common SQL (i.e. Sequel) functionality
 * Improve configuration options
   * HTTP Auth and security
-  * Alternate output formats
+  * Alternate output formats/content types
+  * Primary keys other than `id`
 * Better documentation
 
 
@@ -47,5 +143,7 @@ License
 Copyright (c) 2012 Doug Mayer. Distributed under the MIT License.
 See `MIT-LICENSE` for further details.
 
+[hashie]: https://github.com/intridea/hashie
+[httpary]: http://johnnunemaker.com/httparty/
 [sequel]: http://sequel.rubyforge.org/
 [sinatra]: http://sinatra.restafari.org/

data/bin/expose-db

@@ -9,6 +9,7 @@ require 'expose_db'
 database_uri = nil
 load_libs = []
 server_port = 4567
+public_folder = nil
 
 opts = OptionParser.new do |opts|
   opts.banner = "ExposeDB: Expose your database as an API."
@@ -25,6 +26,10 @@ opts = OptionParser.new do |opts|
     server_port = arg.to_i
   end
 
+  opts.on "-s", "--static DIRECTORY", "Serve static files from DIRECTORY" do |arg|
+    public_folder = File.expand_path(arg)
+  end
+
   opts.on "-r", "--require LIB", "require a driver library (ie: pg, sqlite3, etc)" do |arg|
     load_libs << arg
   end
@@ -39,13 +44,18 @@ opts.parse!
 database_uri = ARGV.shift
 
 if database_uri.nil?
+  puts opts
+  puts ""
   puts "ERROR: Please specify a database URI"
   exit 1
 end
 
 load_libs.each { |lib| require lib }
 
+sinatra_options = {port: server_port}
+sinatra_options[:public_folder] = public_folder if public_folder
+
 db = Sequel.connect(database_uri)
-ExposeDB::App.run!(db, port: server_port)
+ExposeDB::App.run!(db, sinatra_options)
 
 # vim: set ft=ruby:

data/lib/expose_db.rb

@@ -4,3 +4,4 @@ require 'sinatra/base'
 
 require 'expose_db/version'
 require 'expose_db/app'
+require 'expose_db/model'

data/lib/expose_db/app.rb

@@ -32,7 +32,7 @@ module ExposeDB
         @table_name ||= params[:table].to_sym
       end
 
-      def json(obj)
+      def expose(obj)
         MultiJson.dump obj
       end
     end
@@ -52,7 +52,7 @@ module ExposeDB
         dataset = dataset.filter(query, *values)
       end
 
-      json dataset.to_a
+      expose dataset.to_a
     end
 
     get '/:table/:id' do
@@ -61,7 +61,11 @@ module ExposeDB
       id = params[:id]
       dataset = db[table_name]
 
-      json dataset[id: id]
+      if result = dataset[id: id]
+        expose result
+      else
+        raise Sinatra::NotFound
+      end
     end
   end
 end

data/lib/expose_db/model.rb

@@ -0,0 +1,19 @@
+require 'hashie'
+require 'httparty'
+require 'expose_db/model/querying'
+require 'expose_db/model/relations'
+
+module ExposeDB
+  class RecordNotFound < StandardError; end
+
+  class Model < Hashie::Mash
+    include HTTParty
+    extend ExposeDB::Querying
+    extend ExposeDB::Relations
+
+    def self.exposed_as(new_exposed_as = nil)
+      return @exposed_as unless new_exposed_as
+      @exposed_as = new_exposed_as.to_s
+    end
+  end
+end

data/lib/expose_db/model/querying.rb

@@ -0,0 +1,41 @@
+module ExposeDB
+  module Querying
+    def all
+      filter(nil)
+    end
+
+    def filter(query, *values)
+      options = {}
+      if query
+        options[:query] = {q: query}
+        options[:query][:values] = values if values
+      end
+
+      results = MultiJson.load get("/#{exposed_as}", options)
+      results.map { |json| new(json) }
+    end
+
+    # Find a record and raise RecordNotFound if it isn't found.
+    def find(id)
+      find_by_id(id).tap { |result|
+        if result.nil?
+          raise RecordNotFound, "#{self.class.name}#find with ID #{id.inspect} was not found"
+        end
+      }
+    end
+
+    # Find a record or return nil if it isn't found.
+    def find_by_id(id)
+      resp = get("/#{exposed_as}/#{id}")
+      case resp.response.code.to_i
+      when 200
+        result = MultiJson.load resp.parsed_response
+        new(result)
+      when 404
+        nil
+      else
+        raise "#{self.class.name}#try_find with ID #{id.inspect} returned unexpected response: #{resp.inspect}"
+      end
+    end
+  end
+end

data/lib/expose_db/model/relations.rb

@@ -0,0 +1,70 @@
+module ExposeDB
+  module Relations
+    def belongs_to(name, options = {})
+      if options.key?(:class_name)
+        class_name = options.fetch(:class_name).to_s
+      else
+        class_name = name.to_s.titleize
+      end
+
+      foreign_key = (options[:foreign_key] ||
+                     "#{name.to_s.underscore}_id").to_sym
+
+      define_method(name) do
+        found = instance_variable_get(:"@#{name}")
+        return found if found
+
+        if id = send(foreign_key)
+          found = self.class.resolve_relation_class(class_name).find(id)
+          instance_variable_set(:"@#{name}", found)
+        end
+        found
+      end
+    end
+
+    def has_many(plural_name, options = {})
+      singular_name = plural_name.to_s.sub(/s\Z/, '')
+
+      if options.key?(:class_name)
+        class_name = options.fetch(:class_name).to_s
+      else
+        class_name = singular_name.titleize
+      end
+
+      primary_key = (options[:primary_key] || :id).to_sym
+
+      foreign_key = (options[:foreign_key] ||
+                     "#{singular_name.underscore}_id").to_sym
+
+      define_method(plural_name) do
+        found = instance_variable_get(:"@#{plural_name}")
+        return found if found
+
+        relation_class = self.class.resolve_relation_class(class_name)
+        found = relation_class.filter("#{foreign_key} = ?", send(primary_key))
+        instance_variable_set(:"@#{plural_name}", found)
+        found
+      end
+    end
+
+    def resolve_relation_class(class_name)
+      resolved_relation_classes[class_name] ||= constantize_class_from_name(class_name)
+    end
+
+    def resolved_relation_classes
+      @resolved_relation_classes ||= {}
+    end
+
+    # Selected from ActiveSupport
+    def constantize_class_from_name(camel_cased_word)
+      names = camel_cased_word.split('::')
+      names.shift if names.empty? || names.first.empty?
+
+      constant = Object
+      names.each do |name|
+        constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+      end
+      constant
+    end
+  end
+end

data/lib/expose_db/version.rb

@@ -1,7 +1,7 @@
 module ExposeDB
   MAJOR   = 0
-  MINOR   = 1
-  TINY    = 1
+  MINOR   = 2
+  TINY    = 0
 
   VERSION = [MAJOR, MINOR, TINY].join('.')
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: expose_db
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,10 +9,10 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-05 00:00:00.000000000 Z
+date: 2012-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: sinatra
+  name: hashie
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -28,7 +28,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sequel
+  name: httparty
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -59,6 +59,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Expose your database over an API.
 email: doxavore@gmail.com
 executables:
@@ -73,6 +105,9 @@ files:
 - lib/expose_db/version.rb
 - lib/expose_db/app.rb
 - lib/expose_db/views/index.erb
+- lib/expose_db/model/querying.rb
+- lib/expose_db/model/relations.rb
+- lib/expose_db/model.rb
 homepage: https://github.com/doxavore/expose_db
 licenses:
 - MIT