pebblebed 0.0.4 → 0.0.6

data/README.md

@@ -0,0 +1,155 @@
+Pebblebed
+=========
+
+This gem contains a number of tools for ruby that wants to be a good pebble.
+
+Usage
+=====
+
+In your Gemfile:
+
+    gem "pebblebed"
+
+
+Sinatra
+=======
+
+Pebblebed provides a lot of its functionality as a Sinatra extension which is useful for Sinatra
+apps that need to talk to other pebbles - or to conform to the basic pebble-spec.
+
+In you app:
+
+    require "pebblebed/sinatra"
+    
+    class MyPebbleV1 < Sinatra::Base
+      register Sinatra::Pebblebed
+
+      # Declare the name of this pebble
+      i_am :my_pebble
+
+      # Declare which pebbles I need to talk to
+      declare_pebbles do 
+        service :checkpoint, :version => 1
+        service :parlor, :version => 1
+      end
+
+      ... your stuff ...
+
+    end
+
+The extension provide a helper method `pebbles` that can be used to talk to the declared pebbles in this 
+manner:
+
+    pebbles.checkpoint.get("/identities/me")
+
+If the result is valid json, it is parsed and wrapped as a [DeepStruct](https://github.com/simen/deepstruct) record.
+Otherwise it is returned as a string. If an error is returned by the server, the `Pebblebed::HttpError` exception is raised. 
+This exception has the fields `status` and `message`.
+
+Other helper methods provided by this extension:
+
+    part(partspec, params = {})             # Include a part from a kit (See https://github.com/benglerpebbles/kits)
+    parts_script_include_tags               # All script tags required by the kits 
+    parts_stylesheet_include_tags           # All stylesheet-tags required by the kits
+    current_session                         # The hash string that identifies the current browser session
+    pebbles                                 # Common entrypoint for the Pebblebed::Connector
+    current_identity                        # Returns the a DeepStruct record with the vital data for the current user
+    require_identity                        # Halts with 403 if there is no current user
+    current_identity_is?(identity_id)       # Halts with 403 if the current user is neither the provided user or a god
+    require_god                             # Halts with 403 if the current user is not a god
+    require_parameters(parameters, *keys)   # Halts with 409 if the at least one of the provided keys is not in the params-hash
+
+
+Not Sinatra
+===========
+
+If you want to talk to pebbles from other ruby projects, you may use the Pebblebed::Connector directly. To set it up:
+
+    Pebblebed.config do
+      host "mypebbleapp.org" # The host where all your pebbles are mapped
+      service :checkpoint, :version => 1
+      service :grove, :version => 1
+    end
+
+To create a connector do this:
+
+    pebbles = Pebblebed::Connector.new(optional_session_hash)    
+
+If you need to "be" a specific user when you talk to the pebbles you need a session from checkpoint. You provide this
+to your connector when you create it and connector will take care of propagating this information to any pebble you 
+talk to. If you don't plan on doing any authorized request you can omit the session hash.
+
+Then you can start making requests:
+
+    pebbles.checkpoint.get("/identities/1")
+    pebbles.grove.post("/posts/post:mittap.blogs.blog1", :post => {:document => {:body => "This is my blog post"}})
+
+Uid
+===
+
+Objects in the Pebblesphere are identified using Uids which must be unique across the whole pebblesphere. The Uid 
+consists of three parts: The klass of the object, the path and the object id. The format is like this:
+
+    klass:path.of.the.object$object_id
+
+## Klass
+
+The `klass` specifies the type of the object. The klass of the object must map to exactly one pebble that has 
+the responsibility of maintining that specific klass of objects. Currently Parlor maintains `topic` and `comment`, 
+Checkpoint maintains `identity`, `account` and `session`, Grove maintains `post` and Origami maintains `organization`,
+`associate` and more. (Presently there is no registry of which klass belongs in which pebble.)
+
+## Path
+
+The three first nodes of the paths have defined uses: 
+
+The first is the `realm` of the object. A realm corresponds 
+to one installation of an application and no data is supposed to leak between realms. E.g. checkpoint maintains
+a separate list of identities and accounts for each realm, and no identity from one realm is able to log in to another
+realm. 
+
+The second node is the `box`. It roughly corresponds to a 'site' or 'location' in your application. It could typically be
+a website or subsection of your application. E.g. 'forums', 'blogs', 'workspaces'.
+
+The third noe is `collection` and will typically represent a blog, a forum or other closely related collection of objects.
+
+More nodes may be supported by a pebble where applicable. Only the realm is required.
+
+## Object id
+
+The object id is a pebble-internal identification and is to be treated as an opaque string by all other services except 
+for the pebble responsible for maintaining the specific klass. Typically the object_id will be equal to the id of the 
+database-record used internally by the pebble to store that specific object.
+
+Some examples:
+
+    trackers:mittap.user1232$1983
+    post:dittforslag.suggestions.theme1$332
+    topic:playground$post:playground.blogs.blog1$1213  # The object-id can be a full uid. Not presently valid, but TODO
+
+Pebblebed provides a class for processing uids: `Pebblebed::Uid`:
+
+    klass, path, oid = Pebblebed::Uid.parse(an_uid)
+
+It currenty provides no help in building uids, but TODO.
+
+Pebble Clients
+==============
+
+When talking to pebbles, Pebblebed provides a generic http client with the common http-methods get, post, put, delete.
+
+    pebbles.grove.get("/posts/post:mittap.blogs.*")
+    pebbles.parlor.delete("/comments/comment:playground.forums.1$3423")
+
+There is also a special "virtual" pebble that lets you ask all declared pebbles the same thing:
+
+    pebbles.quorum.get("/ping")
+
+It will return a hash with each pebble as the key and the result as the value. If an error occured the value for that 
+pebble is a HttpError object with status and message.
+
+    
+For some pebbles Pebblebed may furnish a richer client with helper methods. This is implemented by sticking the 
+augmented client in the `/lib/pebblebed/clients` folder and naming the class `Pebblebed::<YourPebbleName>Client`. For
+an example of this see `CheckpointClient` which in addition to the common http-methods provides the method `me` which
+returns the logged in user and `god?` which checks whether she's a god(dess).

data/lib/pebblebed/sinatra.rb

@@ -62,9 +62,6 @@ module Sinatra
 
     def self.registered(app)
       app.helpers(Sinatra::Pebblebed::Helpers)
-      app.get "/ping" do
-        "{\"name\":#{(app.service_name || 'undefined').to_s.inspect}}"
-      end
     end
 
     def declare_pebbles(&block)

data/lib/pebblebed/uid.rb

@@ -1,8 +1,14 @@
 module Pebblebed
   class InvalidUid < StandardError; end
   class Uid
-    def initialize(uid)
-      self.klass, self.path, self.oid = self.class.raw_parse(uid)
+    def initialize(args)
+      case args
+        when String
+          self.klass, self.path, self.oid = self.class.raw_parse(args)
+        when Hash
+          self.klass, self.path, self.oid = args[:klass], args[:path], args[:oid]
+        else raise "Invalid argument"
+      end
       raise InvalidUid, "Missing klass in uid" unless self.klass
       raise InvalidUid, "A valid uid must specify either path or oid" unless self.path || self.oid
     end
@@ -43,7 +49,7 @@ module Pebblebed
     end
 
     def self.valid_label?(value)
-      !!(value =~ /^[a-zA-Z0-9_]+$/)
+      !!(value =~ /^[a-zA-Z0-9_-]+$/)
     end
 
     def self.valid_klass?(value)
@@ -60,7 +66,11 @@ module Pebblebed
     end
 
     def self.valid_oid?(value)
-      self.valid_label?(value)
+      !value.nil? && !value.include?('/')
+    end
+
+    def realm
+      self.path.split(".").first if self.path
     end
 
     def inspect

data/lib/pebblebed/version.rb

@@ -1,3 +1,3 @@
 module Pebblebed
-  VERSION = "0.0.4"
+  VERSION = "0.0.6"
 end

data/pebblebed.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "simplecov"
   
   s.add_runtime_dependency "deepstruct"
-  s.add_runtime_dependency "curb"
+  s.add_runtime_dependency "curb", "~> 0.8.0"
   s.add_runtime_dependency "yajl-ruby"
   s.add_runtime_dependency "queryparams"
   s.add_runtime_dependency "futurevalue"

data/spec/uid_spec.rb

@@ -25,34 +25,74 @@ describe Pebblebed::Uid do
     uid.to_s.should eq "klass:$oid"
   end
 
+  it "can be created with a string" do
+    uid = Pebblebed::Uid.new "klass:some.path$oid"
+    uid.to_s.should eq "klass:some.path$oid"
+  end
+
+  it "can be created using parameters" do
+    uid = Pebblebed::Uid.new :klass => 'klass', :path => 'some.path', :oid => 'oid'
+    uid.to_s.should eq "klass:some.path$oid"
+  end
+
+  it "raises an error if parameter is neither string or hash" do
+    lambda {Pebblebed::Uid.new([])}.should raise_exception
+  end
+
   it "raises an exception when you try to create an invalid uid" do
     -> { Pebblebed::Uid.new("!:$298") }.should raise_error Pebblebed::InvalidUid
   end
 
-  it "raises an exception when you modify an uid with an invalid value" do
+  it "raises an exception when you modify a uid with an invalid value" do
     uid = Pebblebed::Uid.new("klass:path$oid")
     -> { uid.klass = "!" }.should raise_error Pebblebed::InvalidUid
     -> { uid.path = "..." }.should raise_error Pebblebed::InvalidUid
-    -> { uid.oid = "(/&%$" }.should raise_error Pebblebed::InvalidUid
+    -> { uid.oid = "/" }.should raise_error Pebblebed::InvalidUid
+  end
+
+  describe "oid" do
+    it "is valid with pretty much anything" do
+      Pebblebed::Uid.valid_oid?("abc123").should be_true
+      Pebblebed::Uid.valid_oid?("abc123!").should be_true
+      Pebblebed::Uid.valid_oid?("abc 123").should be_true
+    end
+
+    it "cannot contain a slash" do
+      Pebblebed::Uid.valid_oid?("abc/123").should be_false
+    end
+
+    it "can contain a full uid" do
+      Pebblebed::Uid.new('klass:path$post:some.path$oid').oid.should eq('post:some.path$oid')
+    end
+
+    it "can be missing" do
+      Pebblebed::Uid.new('klass:path').oid.should be_nil
+    end
+
+    it "is not valid if it is nil" do
+      Pebblebed::Uid.valid_oid?(nil).should be_false
+    end
   end
 
-  it "rejects invalid labels for klass and oid" do
+  it "rejects invalid labels for klass" do
     Pebblebed::Uid.valid_klass?("abc123").should be_true
     Pebblebed::Uid.valid_klass?("abc123!").should be_false
     Pebblebed::Uid.valid_klass?("").should be_false
-    Pebblebed::Uid.valid_oid?("abc123").should be_true
-    Pebblebed::Uid.valid_oid?("abc123!").should be_false
-    Pebblebed::Uid.valid_oid?("abc 123").should be_false
-    Pebblebed::Uid.valid_oid?("").should be_false
   end
 
-  it "rejects invalid paths" do
-    Pebblebed::Uid.valid_path?("abc123").should be_true
-    Pebblebed::Uid.valid_path?("abc.123").should be_true
-    Pebblebed::Uid.valid_path?("").should be_true
-    Pebblebed::Uid.valid_path?("abc!.").should be_false
-    Pebblebed::Uid.valid_path?(".").should be_false
-    Pebblebed::Uid.valid_path?("ab. 123").should be_false
+  describe "path" do
+    it "accepts valid paths" do
+      Pebblebed::Uid.valid_path?("").should be_true
+      Pebblebed::Uid.valid_path?("abc123").should be_true
+      Pebblebed::Uid.valid_path?("abc.123").should be_true
+      Pebblebed::Uid.valid_path?("abc.de-f.123").should be_true
+    end
+
+    it "rejects invalid paths" do
+      Pebblebed::Uid.valid_path?("abc!.").should be_false
+      Pebblebed::Uid.valid_path?(".").should be_false
+      Pebblebed::Uid.valid_path?("ab. 123").should be_false
+    end
   end
 
   it "knows how to parse in place" do
@@ -73,4 +113,17 @@ describe Pebblebed::Uid do
     Pebblebed::Uid.valid?("a:b.c.d").should be_true
   end
 
-end
+  it "knows how to extract the realm from the path" do
+    Pebblebed::Uid.new("klass:realm.other.stuff$3").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:realm$3").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:realm").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:$3").realm.should eq nil
+  end
+
+  it "knows how to extract the realm from the path" do
+    Pebblebed::Uid.new("klass:realm.other.stuff$3").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:realm$3").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:realm").realm.should eq 'realm'
+    Pebblebed::Uid.new("klass:$3").realm.should eq nil
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pebblebed
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-19 00:00:00.000000000Z
+date: 2012-01-25 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70177387541220 !ruby/object:Gem::Requirement
+  requirement: &70255687117880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70177387541220
+  version_requirements: *70255687117880
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70177387539500 !ruby/object:Gem::Requirement
+  requirement: &70255687116600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70177387539500
+  version_requirements: *70255687116600
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70177387538700 !ruby/object:Gem::Requirement
+  requirement: &70255687115440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70177387538700
+  version_requirements: *70255687115440
 - !ruby/object:Gem::Dependency
   name: deepstruct
-  requirement: &70177387537720 !ruby/object:Gem::Requirement
+  requirement: &70255687114700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,21 +55,21 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387537720
+  version_requirements: *70255687114700
 - !ruby/object:Gem::Dependency
   name: curb
-  requirement: &70177387536600 !ruby/object:Gem::Requirement
+  requirement: &70255687113860 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.8.0
   type: :runtime
   prerelease: false
-  version_requirements: *70177387536600
+  version_requirements: *70255687113860
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
-  requirement: &70177387536120 !ruby/object:Gem::Requirement
+  requirement: &70255687113180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +77,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387536120
+  version_requirements: *70255687113180
 - !ruby/object:Gem::Dependency
   name: queryparams
-  requirement: &70177387535660 !ruby/object:Gem::Requirement
+  requirement: &70255687112460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,10 +88,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387535660
+  version_requirements: *70255687112460
 - !ruby/object:Gem::Dependency
   name: futurevalue
-  requirement: &70177387535040 !ruby/object:Gem::Requirement
+  requirement: &70255687111860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -99,10 +99,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387535040
+  version_requirements: *70255687111860
 - !ruby/object:Gem::Dependency
   name: pathbuilder
-  requirement: &70177387534460 !ruby/object:Gem::Requirement
+  requirement: &70255687111240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -110,10 +110,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387534460
+  version_requirements: *70255687111240
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70177387533740 !ruby/object:Gem::Requirement
+  requirement: &70255687110520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -121,10 +121,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387533740
+  version_requirements: *70255687110520
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70177387532700 !ruby/object:Gem::Requirement
+  requirement: &70255687109920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -132,10 +132,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387532700
+  version_requirements: *70255687109920
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70177387531760 !ruby/object:Gem::Requirement
+  requirement: &70255687109260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -143,7 +143,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70177387531760
+  version_requirements: *70255687109260
 description: Development tools for working with Pebblebed
 email:
 - katrina@bengler.no
@@ -155,6 +155,7 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- README.md
 - Rakefile
 - lib/pebblebed.rb
 - lib/pebblebed/clients/abstract_client.rb
@@ -189,12 +190,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -441752401795012861
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -441752401795012861
 requirements: []
 rubyforge_project: pebblebed
 rubygems_version: 1.8.10