fauna 0.0.0 → 0.1

data/CHANGELOG

@@ -0,0 +1,6 @@
+
+
+v0.1. Refactor resource hierarchy. Add cache. Flesh out ActiveModel
+	support.
+
+v0.0. First release.

data/Gemfile

@@ -0,0 +1,6 @@
+source :rubygems
+
+gem 'rake'
+gem 'jruby-openssl', :platform => :jruby
+
+gemspec

data/LICENSE

@@ -0,0 +1,12 @@
+Copyright 2013 Fauna, Inc.
+
+Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may
+not use this software except in compliance with the License. You may obtain a 
+copy of the License at
+
+http://mozilla.org/MPL/2.0/
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

data/Manifest

@@ -0,0 +1,31 @@
+CHANGELOG
+Gemfile
+LICENSE
+Manifest
+README.md
+Rakefile
+fauna.gemspec
+lib/fauna.rb
+lib/fauna/client.rb
+lib/fauna/connection.rb
+lib/fauna/ddl.rb
+lib/fauna/model.rb
+lib/fauna/model/class.rb
+lib/fauna/model/follow.rb
+lib/fauna/model/publisher.rb
+lib/fauna/model/timeline.rb
+lib/fauna/model/user.rb
+lib/fauna/rails.rb
+lib/fauna/resource.rb
+test/client_test.rb
+test/connection_test.rb
+test/fixtures.rb
+test/model/association_test.rb
+test/model/class_test.rb
+test/model/follow_test.rb
+test/model/publisher_test.rb
+test/model/timeline_test.rb
+test/model/user_test.rb
+test/model/validation_test.rb
+test/readme_test.rb
+test/test_helper.rb

data/README.md

@@ -0,0 +1,285 @@
+# Fauna
+
+Ruby client for the [Fauna](http://fauna.org) API.
+
+## Installation
+
+The Fauna ruby client is distributed as a gem. Install it via:
+
+    $ gem install fauna
+
+Or if you use Bundler, add it to your application's `Gemfile`:
+
+    gem 'fauna'
+
+And then execute:
+
+    $ bundle
+
+## Compatibility
+
+Tested and compatible with MRI 1.9.3. Other Rubies may also work.
+
+## Basic Usage
+
+First, require the gem:
+
+```ruby
+require "rubygems"
+require "fauna"
+```
+
+### Configuring the API
+
+All API requests start with an instance of `Fauna::Connection`.
+
+Creating a connection requires either a token, a publisher key, a
+client key, or the publisher's email and password.
+
+Let's use the email and password to get a publisher key:
+
+```ruby
+root = Fauna::Connection.new(email: "publisher@example.com", password: "secret")
+publisher_key = root.post("keys/publisher")['resource']['key']
+```
+
+Now we can make a global publisher-level connection:
+
+```ruby
+$fauna = Fauna::Connection.new(publisher_key: publisher_key)
+```
+
+You can optionally configure a `logger` on the connection to ease
+debugging:
+
+```ruby
+require "logger"
+$fauna = Fauna::Connection.new(publisher_key: publisher_key, logger:
+Logger.new(STDERR))
+```
+
+### Client Contexts
+
+The easiest way to work with a connection is to open up a *client
+context*, and then manipulate resources within that context:
+
+```ruby
+Fauna::Client.context($fauna) do
+  user = Fauna::User.create!(name: "Taran", email: "taran@example.com")
+  user.data["profession"] = "Pigkeeper"
+  user.save!
+  user.destroy
+end
+```
+
+By working within a context, not only are you able to use a more
+convienient, object-oriented API, you also gain the advantage of
+in-process caching.
+
+Within a context block, requests for a resource that has already been
+loaded via a previous request will be returned from the cache and no
+query will be issued. This substantially lowers network overhead,
+since Fauna makes an effort to return related resources as part of
+every response.
+
+### Fauna::Resource
+
+All instances of fauna classes have built-in accessors for common
+fields:
+
+```ruby
+Fauna::Client.context($fauna) do
+  user = Fauna::User.create(external_id: "taran77", name: "Taran")
+
+  # fields
+  user.ref         # => "users/123"
+  user.ts          # => 1359579766996758
+  user.deleted     # => false
+  user.external_id # => "taran77"
+
+  # data and references
+  user.data       # => {}
+  user.references # => {}
+
+  # standard timelines
+  user.changes
+  user.user_follows
+  user.user_followers
+  user.instance_follows
+  user.instance_followers
+  user.local
+end
+```
+
+## Rails Usage
+
+Fauna provides ActiveModel-compatible classes that can be used
+directly in Rails.
+
+Fauna also provides a Rails helper that sets up a default context in
+controllers, based on credentials in `config/fauna.yml`:
+
+```yaml
+development:
+  email: taran@example.com
+  password: secret
+test:
+  email: taran@example.com
+  password: secret
+```
+
+Then, in `config/initializers/fauna.rb`:
+
+```ruby
+require "fauna/rails"
+
+Fauna.schema do
+  # See below for schema setup
+end
+```
+
+### Setting Up the Schema
+
+First, create some Ruby classes to model your domain. They must
+inherit from the `Fauna::Class` base class:
+
+```ruby
+# Create a custom Pig class.
+class Pig < Fauna::Class
+    # Fields can be configured dynamically
+    field :name, :title
+end
+
+# Create a custom Vision class
+class Vision < Fauna::Class
+  field :pronouncement
+  reference :pig
+end
+```
+
+Fields and references can be configured dynamically, but the classes
+and timelines themselves must be configured with an additional
+`Fauna.schema` block (normally placed in
+`config/initializers/fauna.rb`):
+
+```ruby
+Fauna.schema do
+  with Pig do
+    # Add a custom timeline
+    timeline :visions
+  end
+
+  with Vision
+end
+```
+
+Install your schema on the server via a Rake task or the Rails
+console:
+
+```ruby
+Fauna::Client.context(Fauna.connection) do
+  Fauna.migrate_schema!
+end
+```
+
+Make sure to do this at least once, as well as every time you change
+the schema definition:
+
+### Users Class
+
+```ruby
+class Fauna::User
+  # Extend the User class with a custom field
+  field :pockets
+end
+
+# Create a user, fill their pockets, and delete them.
+Fauna::Client.context($fauna) do
+  taran = Fauna::User.new(
+    name: "Taran",
+    email: "taran@example.com",
+    password: "secret")
+
+  taran.save!
+  taran.pockets = "Piggy treats"
+  taran.save!
+  taran.destroy
+end
+```
+
+### Custom Classes
+
+```ruby
+# Create, find, update, and destroy Pigs.
+Fauna::Client.context($fauna) do
+  @pig = Pig.create!(name: "Henwen", external_id: "henwen")
+
+  @pig = Pig.find(@pig.ref)
+  @pig.update(title: "Oracular Swine")
+
+  @pig.title = "Most Illustrious Oracular Swine"
+  @pig.save!
+
+  @pig.destroy
+end
+```
+
+### Timelines
+
+[Timelines](https://fauna.org/API#timelines) are high-cardinality,
+bidirectional event collections. Timelines must be declared in the
+Schema.
+
+```ruby
+Fauna::Client.context($fauna) do
+  @pig = Pig.create!(name: "Henwen", external_id: "henwen")
+
+  @vision = Vision.create!(pronouncement: "In an ominous tower...")
+  @pig.visions.add @vision
+  @pig.visions.page.events.first.resource # => @vision
+end
+```
+
+### References
+
+References are single or low-cardinality, unidirectional, and have no
+event log. They are declared dynamically, in the class.
+
+```ruby
+class Vision
+  # References can be configured dynamically, like fields
+  reference :pig
+end
+
+Fauna::Client.context($fauna) do
+  @vision.pig # => @pig
+  @vision.pig_ref # => "instances/1235921393191239"
+end
+```
+
+## Further Reading
+
+Please see the Fauna [REST Documentation](https://fauna.org/API) for a
+complete API reference, or look in
+[`/tests`](https://github.com/fauna/fauna-ruby/tree/master/test) for
+more examples.
+
+## Contributing
+
+GitHub pull requests are very welcome.
+
+## LICENSE
+
+Copyright 2013 [Fauna, Inc.](https://fauna.org/)
+
+Licensed under the Mozilla Public License, Version 2.0 (the
+"License"); you may not use this software except in compliance with
+the License. You may obtain a copy of the License at
+
+[http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/)
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing
+permissions and limitations under the License.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'echoe'
+
+Echoe.new("fauna") do |p|
+  p.author = "Fauna, Inc."
+  p.project = "fauna"
+  p.summary = "Official Ruby client for the Fauna API."
+  p.retain_gemspec = true
+  p.dependencies = ["activemodel", "activesupport", "rest-client", "json"]
+  p.development_dependencies = ["mocha", "echoe", "minitest"]
+end
+
+task :beautify do
+  require "ruby-beautify"
+  Dir["**/*rb"].each do |filename|
+    s = RBeautify.beautify_string(:ruby, File.read(filename))
+    File.write(filename, s) unless s.empty?
+   end
+end
+
+task :prerelease => [:manifest, :test, :install]

data/fauna.gemspec

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "fauna"
+  s.version = "0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Fauna, Inc."]
+  s.cert_chain = ["/Users/eweaver/cloudburst/configuration/gem_certificates/evan_weaver-original-public_cert.pem"]
+  s.date = "2013-02-08"
+  s.description = "Official Ruby client for the Fauna API."
+  s.email = ""
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.md", "lib/fauna.rb", "lib/fauna/client.rb", "lib/fauna/connection.rb", "lib/fauna/ddl.rb", "lib/fauna/model.rb", "lib/fauna/model/class.rb", "lib/fauna/model/follow.rb", "lib/fauna/model/publisher.rb", "lib/fauna/model/timeline.rb", "lib/fauna/model/user.rb", "lib/fauna/rails.rb", "lib/fauna/resource.rb"]
+  s.files = ["CHANGELOG", "Gemfile", "LICENSE", "Manifest", "README.md", "Rakefile", "fauna.gemspec", "lib/fauna.rb", "lib/fauna/client.rb", "lib/fauna/connection.rb", "lib/fauna/ddl.rb", "lib/fauna/model.rb", "lib/fauna/model/class.rb", "lib/fauna/model/follow.rb", "lib/fauna/model/publisher.rb", "lib/fauna/model/timeline.rb", "lib/fauna/model/user.rb", "lib/fauna/rails.rb", "lib/fauna/resource.rb", "test/client_test.rb", "test/connection_test.rb", "test/fixtures.rb", "test/model/association_test.rb", "test/model/class_test.rb", "test/model/follow_test.rb", "test/model/publisher_test.rb", "test/model/timeline_test.rb", "test/model/user_test.rb", "test/model/validation_test.rb", "test/readme_test.rb", "test/test_helper.rb"]
+  s.homepage = "http://fauna.github.com/fauna/"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Fauna", "--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "fauna"
+  s.rubygems_version = "1.8.23"
+  s.signing_key = "/Users/eweaver/cloudburst/configuration/gem_certificates/evan_weaver-original-private_key.pem"
+  s.summary = "Official Ruby client for the Fauna API."
+  s.test_files = ["test/client_test.rb", "test/connection_test.rb", "test/model/association_test.rb", "test/model/class_test.rb", "test/model/follow_test.rb", "test/model/publisher_test.rb", "test/model/timeline_test.rb", "test/model/user_test.rb", "test/model/validation_test.rb", "test/readme_test.rb", "test/test_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activemodel>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 0"])
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+    else
+      s.add_dependency(%q<activemodel>, [">= 0"])
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<rest-client>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+      s.add_dependency(%q<minitest>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activemodel>, [">= 0"])
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<rest-client>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+    s.add_dependency(%q<minitest>, [">= 0"])
+  end
+end

data/lib/fauna.rb

@@ -0,0 +1,98 @@
+require "json"
+require "logger"
+
+require "restclient"
+require "active_model"
+require "active_support/inflector"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/hash/slice"
+
+module Fauna
+  class Invalid < RuntimeError
+  end
+
+  class NotFound < RuntimeError
+  end
+
+  class MissingMigration < RuntimeError
+  end
+end
+
+require "fauna/connection"
+require "fauna/client"
+require "fauna/resource"
+require "fauna/model"
+require "fauna/model/class"
+require "fauna/model/follow"
+require "fauna/model/publisher"
+require "fauna/model/timeline"
+require "fauna/model/user"
+require "fauna/ddl"
+
+module Fauna
+
+  DEFAULT_BLOCK = proc do
+    with User, class_name: "users"
+    with User::Settings, class_name: "users/settings"
+    with Follow, class_name: "follows"
+    with TimelinePage, class_name: "timelines"
+    with TimelineSettings, class_name: "timelines/settings"
+    with ClassSettings, class_name: "classes"
+    with Publisher, class_name: "publisher"
+  end
+
+  def self.configure_schema!
+    @_classes = {}
+    @schema = Fauna::DDL.new
+    @_blocks.each { |blk| @schema.instance_eval(&blk) }
+    @schema.configure!
+    nil
+  end
+
+  def self.schema(&block)
+    @_blocks << block
+    configure_schema!
+  end
+
+
+  def self.reset_schema!
+    @_blocks = [DEFAULT_BLOCK]
+    configure_schema!
+  end
+
+  def self.migrate_schema!
+    @schema.load!
+    nil
+  end
+
+  # these should be private to the gem
+
+  def self.exists_class_for_name?(class_name)
+    !!@_classes[class_name]
+  end
+
+  def self.add_class(class_name, klass)
+    klass.fauna_class_name = class_name.to_s
+    @_classes.delete_if { |_, v| v == klass }
+    @_classes[class_name.to_s] = klass
+  end
+
+  def self.class_for_name(class_name)
+    @_classes[class_name] ||=
+    if class_name =~ %r{^classes/[^/]+$}
+      klass = begin $1.classify.constantize rescue NameError; nil end
+      if klass.nil? || klass >= Fauna::Class || klass.fauna_class_name
+        klass = ::Class.new(Fauna::Class)
+      end
+
+      klass.fauna_class_name = class_name
+      klass
+    else
+      ::Class.new(Fauna::Resource)
+    end
+  end
+
+  # apply the default schema so that the built-in classes work
+
+  reset_schema!
+end