syncano 3.1.4 → 4.0.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8fa33e829552d449652567e0ccf85426f4b31d9e
+  data.tar.gz: 877390535ea162188215684f8b7f58adb788b45b
+SHA512:
+  metadata.gz: 8d4a6780ef77bda1100d9f09d5b833e9659890ca318442887a55d6aab5b6685cff320a13912376ba35547db826edd6ae82cec55be4b0a593274252941d68b415
+  data.tar.gz: 7077b7034ae4bf1189367c5582996579313d630330729d1cc800ab4ca5a71c3a5acf9a5558c8da89e51d391e633a9fce587bb7ae4fca9940a5fffa4092ced573

data/.gitignore

@@ -22,4 +22,7 @@ tmp
 mkmf.log
 .DS_Store
 .com.apple.timemachine.supported
-.idea/*
+.idea/*
+.ruby-gemset
+.env
+profiles

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,3 @@
+AllCops:
+  Exclude:
+    - syncano.gemspec

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.5

data/Gemfile

@@ -1,4 +1,28 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in syncano.gemspec
 gemspec
+
+group :console do
+  gem 'pry'
+end
+
+group :test do
+  gem 'dotenv'
+  gem 'rspec'
+  gem 'webmock'
+  gem 'shoulda-matchers', require: false
+  gem 'rspec-prof', git: 'https://github.com/sinisterchipmunk/rspec-prof.git'
+end
+
+group :tools do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+
+  gem 'rubocop', require: false
+
+  platform :mri do
+    gem 'mutant'
+    gem 'mutant-rspec'
+  end
+end

data/Guardfile

@@ -1,5 +1,23 @@
-guard :rspec do
-  watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch('spec/spec_helper.rb') { rspec.spec_dir }
+  watch('spec/**/*_spec.rb') { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  watch(ruby.lib_files) { rspec.spec_dir }
 end
+
+# guard :rubocop do
+# watch(%r{.+\.rb$})
+# watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+# end

data/README.md

@@ -1,503 +1,124 @@
-# Syncano
+# Syncano 4.0 ruby gem
 
-Syncano ruby gem provides communication with Syncano ([www.syncano.com](http://www.syncano.com)) via HTTPS RESTful interface and TCP sockets.
-
-The full source code can be found on [Github](https://github.com/Syncano/syncano-ruby) - feel free to browse or contribute.
-
-Click here to learn more about [Syncano](http://www.syncano.com) or [create an account](https://login.syncano.com/sign_up)!
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-    gem 'syncano', '~> 3.1'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install syncano -v 3.1.3
-    
-At the end generate initializer with api key and api instance name:
-
-    $ rails g syncano:install
-
-Initializer is not obligatory - you can provide both parameters directly in the client's constructor.
-
-## Usage
-
-### Clients
-
-There are two different class of clients. One for JSON RPC interface and one for socket connections with Sync Server. You can use both in quite similar way:
-
-```ruby
-client = Syncano.client
-
-client = Syncano.sync_client
-```
-    
-You can provide specific api credentials when you are initializing your client:
-
-```ruby
-client = Syncano.client(api_key: 'api key', instance_name: 'instance name')
-
-client = Syncano.sync_client(api_key: 'api key', instance_name: 'instance name')
-```
-
-Sync client has some additional features like:
-
-* managing connections
-```ruby
-client.connect
-client.reconnect
-client.disconnect
-```
-* managing callbacks for handling notifications (it is described later in this document)
-
-#### User api key
-
-If you want to use an user api key, you have to pass auth key or username and password to the client's constructor.
-
-```ruby
-client = Syncano.client(api_key: 'api key', instance_name: 'instance name', auth_key: 'auth key')
-```
-
-```ruby
-client = Syncano.client(api_key: 'api key', instance_name: 'instance name', username: 'username', password: 'password')
-```
-
-### Resources
-
-Syncano gem utilizes an ActiveRecord pattern for managing resources. You can use it in similar way with both type of clients.
-
-Below is a list of standard methods implemented in resources.
-
-* objects.all(parameters)
-* objects.count(parameters)
-* objects.first(parameters)
-* objects.last(parameters)
-* objects.find(id)
-* objects.new(attributes)
-* objects.create(attributes)
-* object.update(attributes)
-* object.save
-* object.destroy
-
-Some of resources do not implement all standard methods and others have some custom methods, ie. data_object.copy.
-
-Every resource has attributes which can be accessed as a hash ie.:
-
-* object[:attribute]
-* object[:attribute] = 'value'
-* object.attributes = { attribute: 'value' }
-
-Below is a list of all implemented resources with information about what methods are implemented and usage examples.
-
-#### Project
-
-Implements all standard methods and following custom:
-
-* project.authorize(api_key_id, permission)
-
-##### Examples
-
-* Getting all projects
-
-```ruby
-Syncano.projects.all
-```
-
-* Creating a project
-
-```ruby
-Syncano.projects.create(name: 'Project name')
-```
-
-* Updating a project
-
-```ruby
-project[:description] = 'Lorem ipsum'
-project.save
-```
-
-* Authorizing user api key with read permission
-
-```ruby
-project.authorize(api_key_id, 'read_data')
-```
-
-#### Collection
-
-Implements all standard methods and following custom:
-
-* collections.find_by_key(collection_key)
-* collection.activate
-* collection.deactivate
-* collection.add_tag(tag, weight, remove_others)
-* collection.delete_tag(tag)
-* collection.authorize(api_key_id, permission)
-
-##### Examples
-
-* Getting all
-
-```ruby
-project.collections.all
-```
-
-* Finding by key
+Using gems:
 
-```ruby
-project.collections.find_by_key(collection_key)
-```
-
-* Activating
-
-```ruby
-collection.activate
-```
-
-* Adding tags
-
-```ruby
-collection1.add_tags(['tag1', 'tag2'], 3)
-collection2.add_tags('tag3', 1, true)
+```bash
+$ gem install syncano --pre
 ```
 
-#### Folder
-
-Implements all standard methods and following custom:
-
-* folders.find_by_name(folder_name)
-* folder.authorize(api_key_id, permission)
-
-Find method uses folder name as a key.
+## First steps
 
-##### Examples
-
-* Getting one
-
-```ruby
-collection.folders.find(folder_name)
-collection.folders.find_by_name(folder_name)
-```
-
-#### Data object
-
-Implements all standard methods and following custom:
-
-* data_objects.find_by_key(data_object_key)
-* data_objects.move(data_object_ids, new_folder, new_state)
-* data_object.move(new_folder, new_state)
-* data_objects.copy(data_object_ids)
-* data_object.copy
-* data_object.add_parent(parent_id, remove_other)
-* data_object.remove_parent(parent_id)
-* data_object.add_child(parent_id, remove_other)
-* data_object.remove_child(parent_id)
-
-##### Examples
-
-* Moving data object to the new folder
-
-```ruby
-data_object.move('new_folder')
-```
+After installation, you have to set a path for api root for syncano.
 
-* Copying two data objects
+If you want to use staging, export:
 
-```ruby
-collection.data_objects.copy([112, 3871])
+```bash
+$ export API_ROOT=https://v4.hydraengine.com
 ```
 
-* Adding parent to the data object
+If you're less adventurous, use our production api servers:
 
-```ruby
-data_object.add_parent(parent_object_id, true)
+```bash
+$ export=API_ROOT=https://api.syncano.io
 ```
 
-#### Admin
-
-Implements all standard methods and following custom:
-
-* admin.find_by_email(email)
-
-#### Api key
-
-Implements all standard methods.
-
-#### Role
-
-Implements only following standard methods:
-
-* role.all
-* role.first
-* role.last
-* role.count
-
-#### User
-
-Implements all standard methods.
-
-### Batch requests
-
-It is possible to make batch requests to the JSON RPC endpoint. You do not have to care about batch requests limits specified in the Syncano api docs. This library will care about queuing for you.
+Ok, now we can start coding!
 
 ```ruby
-client = Syncano.client
-responses = client.batch do |queue|
-  queue << collection.batch.save
-  queue << collection.data_objects.batch.create(title: 'Lorem ipsum')
-  queue.add(data_object.batch.destroy)
-end
-```
+require 'syncano'
 
-There is no difference between "queue.add" and "queue <<" methods.
+syncano = Syncano.connect(api_key: 'your-api-key')
 
-In the above example variable responses will contain three Syncano::Response objects.
-Remember that batch responses do not change objects used in batch requests. If you want to see changes you have to reload them:
-
-```ruby
-collection.reload
+syncano.instances.all.each { |instance| puts instance }
 ```
 
-### Notifications
-
-Main advantage of using Sync Server are real time notifications. This concept is well described in the Syncano api documentation.
+You can either pass your API key to the connect method as above or set
+`ENV['SYNCANO_API_KEY']` and call just `Syncano.connect`.
 
-#### Subscriptions
+## API basics
 
-Before you will receive any notification, you have to subscribe to some project or collection:
-
-```ruby
-client = Syncano.sync_client
-project = client.project.find(project_id)
-project.subscribe
-```
-
-If you want to stop receiving notifications, you have to unsubscribe:
-```ruby
-project.unsubscribe
-```
+Syncano API is a nested API - all the endpointes are scoped by an instances, ex.
+codeboxes path is `/instance/your_instance_name/codeboxes/`. Syncano instances
+is more less a schema is in relation databases. **Your instance name must be
+unique across all existing Syncano instnaces, not only limitted to your account.**
 
-You can also list all active subscriptions:
-```ruby
-client.subscriptions.all
-```
 
-#### Handling notifications
+# Instances
 
-Notifications are handled by callbacks passed to the sync client:
+In order to do anything with Syncano, you have to create an instances. Choose a
+globally unique name and call:
 
 ```ruby
-client.append_callback(:callback_name) do |notification|
-  p "We have received a new notification #{notification.inspect}! Yaaay!"
-end
-```
-
-Callbacks form a queue. You can add new callback to the end of the queue (like above) or to the beginning:
+instances = syncano.instances.create name: 'my_instances_name'       
+instance.first
 
-```ruby
-client.prepend_callback(:callback_name) do |notification|
-  p "We have received a new notification #{notification.inspect}! Yaaay!"
-end
+#=> #<Syncano::Resources::Instance created_at: Sun, 26 Apr 2015 18:09:46 +0000, description: "", metadata: {}, name: "my_instance_name", owner: nil, role: "full", updated_at: Sun, 26 Apr 2015 18:09:46 +0000>
 ```
 
-To delete callback from the queue just call remove_callback method:
- 
-```ruby
-client.remove_callback(:callback_name)
-```
+# Classes and objects
 
-To list notifications ie. after connection use all method:
+In order to save objects in Syncano, first you need to create a class. A class
+defines objects' attributes in the class' schema. The attribute definition has two
+mandatory (`name`, `type`) and two optional fields (`filter_index`, `order_index`).
+What these fields are for is rather obvious - `name` defines objects' attribute
+name, and `type` defines type (you can read more about available types in the 
+[API docs](http://docs.syncano.com/v0.1/docs/instancesinstanceclasses-2)). `*_index`
+fields are indexing. `order_index` allows you order returned collections, 
+`filter_index` allows filtering in a various ways. There will be a few examples
+in this README, but you can read in the 
+[API docs](http://docs.syncano.com/v0.1/docs/filtering-data-objects).
 
 ```ruby
-client.notifications.all
+  stock = instance.classes.create name: 'stock_items',
+                                  schema: [{ name: 'name', type: 'string',
+                                             filter_index: true },
+                                           { name: 'amount', type: 'integer',
+                                             filter_index: true,
+                                             order_index: true }]
 ```
 
-#### Sending notifications
-
-To send notification just create new notification object:
+Once we have a class, we can start creating objects. 
 
 ```ruby
-client.notifications.create(key: 'value')
+  chorizo = stock.objects.create name: 'Chorizo', amount: 100
+  black_pudding = stock.objects.create name: 'Black pudding', amount: 200
+  curry_wurts = stock.objects.create name: 'Curry wurst', amount: 150
+  kabanos = stock.objects.create name: 'Kabanos' 
+  something = stock.objects.create amount: 3
 ```
 
-You can also pass additional attributes specified for api 'notification.send' method:
+Now we have a few items in stock, let's try filtering. 
 
 ```ruby
-client.notifications.create(key: 'value', api_client_id: 512)
+  stock.objects.all(order_by: '-amount', query: { amount: { _lte: 150 }, name: { _exists: true } })
+  #=> #<Syncano::Resources::Collection:0x007fc18b9c7698 @next=false, @prev=false, @collection=[#<Syncano::Resources::Object amount: 150, channel: nil, channel_room: nil, created_at: Mon, 27 Apr 2015 05:21:31 +0000, group: nil, group_permissions: "none", id: 12, name: "Curry wurst", other_permissions: "none", owner: nil, owner_permissions: "none", revision: 1, updated_at: Mon, 27 Apr 2015 05:21:31 +0000>, #<Syncano::Resources::Object amount: 100, channel: nil, channel_room: nil, created_at: Mon, 27 Apr 2015 05:21:30 +0000, group: nil, group_permissions: "none", id: 10, name: "Chorizo", other_permissions: "none", owner: nil, owner_permissions: "none", revision: 1, updated_at: Mon, 27 Apr 2015 05:21:30 +0000>]> 
 ```
 
-### Errors and exceptions
-
-This library does not implement any validations. All errors from the api will cause throwing an exception.
-It is thought that user will create his own validation mechanisms specific not only for restrictions imposed by the Syncano, but also for his own logic.
-It can be compared to the exceptions after violating constraints in the MySQL database.
-
-### Integration with Ruby on Rails
-
-Syncano gem provides handy class for implementing model with ActiveRecord pattern. See example below: 
+Let's give `something` a name and try again.
 
 ```ruby
-class Category < Syncano::ActiveRecord::Base
-  has_many :articles
+  something.name = 'Unidentified sausage' 
+  something.save
   
-  attribute :name, type: String
-  validates :name, presence: true  
-end
-
-class Article < Syncano::ActiveRecord::Base
-  belongs_to :category
-  
-  attribute :title, type: String
-  attribute :text, type: String
-  attribute :promoted, type: Integer, filterable: :data1
-  validates :title, presence: true
-  validates :text, presence: true
-  
-  scope :promoted, -> { where('promoted = ?', 1) }
-  
-  before_save :sanitize_content
-  
-  private
-  
-  def sanitize_content
-    self.title = Sanitize.clean(title)
-    self.text = Sanitize.clean(text)
-  end
-end
-```
-
-#### Attributes
-
-As you can see above every attribute has to be declared with a type. Every ActiveRecord class has also three standard attributes:
-- :id, type: Integer
-- :created_at, type: DateTime
-- :updated_at, type: DateTime
-
-There can be up to three filterable attributes (mapped to the Syncano data1, data2, data3 attributes), which can be used in where and order clauses. They always should have Integer type.
-   
-Attributes can be validated like in standard ActiveRecord.
-
-#### Scopes and query building
-
-You can sort and filter by filterable attributes:
-
-```ruby
-where('attribute1 > ? AND attribute2 <= ?', 0, 30).order('attribute3 ASC').where('attribute 2 > ?', 5)
-```
-
-As you can see methods can be chained. 
-
-#### Callbacks
-
-There are available ten different callbacks fired in the following sequence:
-
-1. before_validation
-2. after_validation
-3. before_save
-4. before_create / before_update
-5. after_create / after_save
-6. after_save
-
-1. before_destroy
-2. after_destroy
-
-#### Associations
-
-There are three types of relations (belongs_to, has_one, has_many) which are based on Syncano parent - child mechanism.
-
-##### belongs_to :category
-
-Adds following methods:
-
-```ruby
-self.category
-self.category = Category.first
-self.category_id
-self.category_id = Category.first.id
-```
-
-Remember to always declare belongs_to association! It creates proper attribute in model.
-
-##### has_one :article
-
-```ruby
-self.article
-self.article = Article.first # this method updates article object
-self.build_article(article_attributes)
-self.create_article(article_attributes)
-```
-
-##### has_many :articles
-
-```ruby
-self.articles
-self.articles = Article.first(5) # this method updates each article object
-self.articles << Article.first # this method updates article object
-self.articles.build(article_attributes)
-self.articles.create(article_attributes)
-```
-
-You can also call scope builder methods on has_many collection:
-
-```ruby
-self.articles.promoted.all
-```
-
-#### Other useful methods in examples
-
-```ruby
-Article.promoted.find(id)
-Article.where('promoted = ?', 0).count
-Article.since(min_id).before(max_id)
-Article.since(Time.now - 10.days)
+  stock.objects.all(order_by: '-amount', query: { amount: { _lte: 150 }, name: { _exists: true } })
+  #=> #<Syncano::Resources::Collection:0x007fc18d58a628 @next=false, @prev=false, @collection=[#<Syncano::Resources::Object amount: 150, channel: nil, channel_room: nil, created_at: Mon, 27 Apr 2015 05:21:31 +0000, group: nil, group_permissions: \"none\", id: 12, name: \"Curry wurst\", other_permissions: \"none\", owner: nil, owner_permissions: \"none\", revision: 1, updated_at: Mon, 27 Apr 2015 05:21:31 +0000>, #<Syncano::Resources::Object amount: 100, channel: nil, channel_room: nil, created_at: Mon, 27 Apr 2015 05:21:30 +0000, group: nil, group_permissions: \"none\", id: 10, name: \"Chorizo\", other_permissions: \"none\", owner: nil, owner_permissions: \"none\", revision: 1, updated_at: Mon, 27 Apr 2015 05:21:30 +0000>, #<Syncano::Resources::Object amount: 3, channel: nil, channel_room: nil, created_at: Mon, 27 Apr 2015 05:30:18 +0000, group: nil, group_permissions: \"none\", id: 15, name: \"Unidentified sausage\", other_permissions: \"none\", owner: nil, owner_permissions: \"none\", revision: 2, updated_at: Mon, 27 Apr 2015 05:30:48 +0000>]>
 ```
 
-For all methods please see reference for Syncano::ActiveRecord::Base class.
+Now it matches the query and appears in the result.
 
-#### Collection and folders
+# Codeboxes
 
-Classes which inherit from Syncano::ActiveRecord::Base needs a collection and a folders in Syncano. 
-
-Collection can be configured as constant in initializer:
- 
-```ruby
-SYNCANO_ACTIVERECORD_COLLECTION = Syncano.client.project.first.collection.first
-```
+Codeboxes are small pieces of code that run on Syncano servers. You can run them
+manually using the API, you can create a schedule to run them periodically, you 
+can create a Webhook (and optionally make it public) to run them from the web, 
+you can create a trigger to run one after a class' object is created, updated or 
+deleted. There are three runtimes available: Ruby, Python and Node. This gem is 
+available in Ruby runtime (just needs to be required).
 
-or it can be overwritten in selected model:
 
-```ruby
-class Article < Syncano::ActiveRecord::Base
-
-  private
-  
-  def self.collection
-    Syncano.client.project.first.collection.first
-  end
-end
-```
-
-Folders are used as classes - each model as his own folder (ie. Articles). Folder is automatically created and used without any additional configuration, but you can customize convention by overwriting folder_name or folder method:
-
-```ruby
-class Article < Syncano::ActiveRecord::Base
-
-  private
-  
-  def self.folder_name
-    'Posts'
-  end
-  
-  def self.folder
-    collection.folders.find_by_name(folder_name)
-  end
-end
-```
 
 ## Contributing