Cistern

Cistern helps you consistently build your API clients and faciliates building mock support.

Usage

Client

This represents the remote service that you are wrapping. It defines the client’s namespace and initialization parameters.

Client initialization parameters are enumerated by requires and recognizes. Parameters defined using recognizes are optional.

# lib/blog.rb
class Blog
  include Cistern::Client
  requires :hmac_id, :hmac_secret
  recognizes :url
end
# Acceptable
Blog.new(hmac_id: "1", hmac_secret: "2")                            # Blog::Real
Blog.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Blog::Real
# ArgumentError
Blog.new(hmac_id: "1", url: "http://example.org")
Blog.new(hmac_id: "1")

Cistern will define for two namespaced classes, Blog::Mock and Blog::Real. Create the corresponding files and initialzers for your new service.

# lib/blog/real.rb
class Blog::Real
  attr_reader :url, :connection
  def initialize(attributes)
    @hmac_id, @hmac_secret = attributes.values_at(:hmac_id, :hmac_secret)
    @url = attributes[:url] || 'http://blog.example.org'
    @connection = Faraday.new(url)
  end
end

# lib/blog/mock.rb
class Blog::Mock
  attr_reader :url
  def initialize(attributes)
    @url = attributes[:url]
  end
end

Mocking

Cistern strongly encourages you to generate mock support for your service. Mocking can be enabled using mock!.

Blog.mocking?          # falsey
real = Blog.new        # Blog::Real
Blog.mock!
Blog.mocking?          # true
fake = Blog.new        # Blog::Mock
Blog.unmock!
Blog.mocking?          # false
real.is_a?(Blog::Real) # true
fake.is_a?(Blog::Mock) # true

Requests

Requests are defined by subclassing #{service}::Request.

• cistern represents the associated Blog instance.
• #call represents the primary entrypoint. Invoked when calling client#{request_method}.
• #dispatch determines which method to call. (#mock or #real)

For example:

class Blog::UpdatePost
  include Blog::Request
  def real(id, parameters)
    cistern.connection.patch("/post/#{id}", parameters)
  end
  def mock(id, parameters)
    post = cistern.data[:posts].fetch(id)
    post.merge!(stringify_keys(parameters))
    response(post: post)
  end
end

However, if you want to add some preprocessing to your request’s arguments override #call and call #dispatch. You
can also alter the response method’s signatures based on the arguments provided to #dispatch.

class Blog::UpdatePost
  include Blog::Request
  attr_reader :parameters
  def call(post_id, parameters)
    @parameters = stringify_keys(parameters)
    dispatch(Integer(post_id))
  end
  def real(id)
    cistern.connection.patch("/post/#{id}", parameters)
  end
  def mock(id)
    post = cistern.data[:posts].fetch(id)
    post.merge!(parameters)
    response(post: post)
  end
end

The #cistern_method function allows you to specify the name of the generated method.

class Blog::GetPosts
  include Blog::Request
  cistern_method :get_all_the_posts
  def real(params)
    "all the posts"
  end
end
Blog.new.respond_to?(:get_posts) # false
Blog.new.get_all_the_posts       # "all the posts"

All declared requests can be listed via Cistern::Client#requests.

Blog.requests # => [Blog::GetPosts, Blog::GetPost]

Models

• cistern represents the associated Blog::Real or Blog::Mock instance.
• collection represents the related collection.
• new_record? checks if identity is present
• requires(*requirements) throws ArgumentError if an attribute matching a requirement isn’t set
• requires_one(*requirements) throws ArgumentError if no attribute matching requirement is set
• merge_attributes(attributes) sets attributes for the current model instance
• dirty_attributes represents attributes changed since the last merge_attributes. This is useful for using update

Attributes

Cistern attributes are designed to make your model flexible and developer friendly.

• attribute :post_id adds an accessor to the model.

    attribute :post_id
    model.post_id #=> nil
    model.post_id = 1 #=> 1
    model.post_id #=> 1
    model.attributes #=> {'post_id' => 1 }
    model.dirty_attributes #=> {'post_id' => 1 }

• identity represents the name of the model’s unique identifier. As this is not always available, it is not required.

    identity :name

  creates an attribute called name that is aliased to identity.

    model.name = 'michelle'
    model.identity   #=> 'michelle'
    model.name       #=> 'michelle'
    model.attributes #=> {  'name' => 'michelle' }

• :aliases or :alias allows a attribute key to be different then a response key.

    attribute :post_id, alias: "post"

  allows

    model.merge_attributes("post" => 1)
    model.post_id #=> 1

• :type automatically casts the attribute do the specified type. Supported types: array, boolean, date, float, integer, string, time.

    attribute :private_ips, type: :array
    model.merge_attributes("private_ips" => 2)
    model.private_ips #=> [2]

• :squash traverses nested hashes for a key.

    attribute :post_id, aliases: "post", squash: "id"
    model.merge_attributes("post" => {"id" => 3})
    model.post_id #=> 3

Persistence

• save is used to persist the model into the remote service. save is responsible for determining if the operation is an update to an existing resource or a new resource.
• reload is used to grab the latest data and merge it into the model. reload uses collection.get(identity) by default.
• update(attrs) is a merge_attributes and a save. When calling update, dirty_attributes can be used to persist only what has changed locally.

For example:

class Blog::Post
  include Blog::Model
  identity :id, type: :integer
  attribute :body
  attribute :author_id, aliases: "author",  squash: "id"
  attribute :deleted_at, type: :time
  def destroy
    requires :identity
    data = cistern.destroy_post(params).body['post']
  end
  def save
    requires :author_id
    response = if new_record?
                 cistern.create_post(attributes)
               else
                 cistern.update_post(dirty_attributes)
               end
    merge_attributes(response.body['post'])
  end
end

Usage:

create

blog.posts.create(author_id: 1, body: 'text')

is equal to

post = blog.posts.new(author_id: 1, body: 'text')
post.save

update

post = blog.posts.get(1)
post.update(author_id: 1) #=> calls #save with #dirty_attributes == { 'author_id' => 1 }
post.author_id #=> 1

Singular

Singular resources do not have an associated collection and the model contains the get andsave methods.

For instance:

class Blog::PostData
  include Blog::Singular
  attribute :post_id, type: :integer
  attribute :upvotes, type: :integer
  attribute :views, type: :integer
  attribute :rating, type: :float
  def get
    response = cistern.get_post_data(post_id)
    merge_attributes(response.body['data'])
  end
  def save
    response = cistern.update_post_data(post_id, dirty_attributes)
    merge_attributes(response.data['data'])
  end
end

Singular resources often hang off of other models or collections.

class Blog::Post
  include Cistern::Model
  identity :id, type: :integer
  def data
    cistern.post_data(post_id: identity).load
  end
end

They are special cases of Models and have similar interfaces.

post.data.views #=> nil
post.data.update(views: 3)
post.data.views #=> 3

Collection

• model tells Cistern which resource class this collection represents.
• cistern is the associated Blog::Real or Blog::Mock instance
• attribute specifications on collections are allowed. use merge_attributes
• load consumes an Array of data and constructs matching model instances

class Blog::Posts
  include Blog::Collection
  attribute :count, type: :integer
  model Blog::Post
  def all(params = {})
    response = cistern.get_posts(params)
    data = response.body
    load(data["posts"])    # store post records in collection
    merge_attributes(data) # store any other attributes of the response on the collection
  end
  def discover(author_id, options={})
    params = {
      "author_id" => author_id,
    }
    params.merge!("topic" => options[:topic]) if options.key?(:topic)
    cistern.blogs.new(cistern.discover_blog(params).body["blog"])
  end
  def get(id)
    data = cistern.get_post(id).body["post"]
    new(data) if data
  end
end

Associations

Associations allow the use of a resource’s attributes to reference other resources. They act as lazy loaded attributes
and push any loaded data into the resource’s attributes.

There are two types of associations available.

• belongs_to references a specific resource and defines a reader.
• has_many references a collection of resources and defines a reader / writer.

class Blog::Tag
  include Blog::Model
  identity :id
  attribute :author_id
  has_many :posts -> { cistern.posts(tag_id: identity) }
  belongs_to :creator -> { cistern.authors.get(author_id) }
end

Relationships store the collection’s attributes within the resources’ attributes on write / load.

tag = blog.tags.get('ruby')
tag.posts = blog.posts.load({'id' => 1, 'author_id' => '2'}, {'id' => 2, 'author_id' => 3})
tag.attributes[:posts] #=> {'id' => 1, 'author_id' => '2'}, {'id' => 2, 'author_id' => 3}
tag.creator = blogs.author.get(name: 'phil')
tag.attributes[:creator] #=> { 'id' => 2, 'name' => 'phil' }

Foreign keys can be updated by overriding the association writer.

Blog::Tag.class_eval do
  def creator=(creator)
    super
    self.author_id = attributes[:creator][:id]
  end
end
tag = blog.tags.get('ruby')
tag.author_id = 4
tag.creator = blogs.author.get(name: 'phil') #=> #<Blog::Author id=2 name='phil'>
tag.author_id #=> 2

Data

A uniform interface for mock data is mixed into the Mock class by default.

Blog.mock!
client = Blog.new # Blog::Mock
client.data       # Cistern::Data::Hash
client.data["posts"] += ["x"] # ["x"]

Mock data is class-level by default

Blog::Mock.data["posts"] # ["x"]

reset! dimisses the data object.

client.data.object_id # 70199868585600
client.reset!
client.data["posts"]  # []
client.data.object_id # 70199868566840

clear removes existing keys and values but keeps the same object.

client.data["posts"] += ["y"] # ["y"]
client.data.object_id         # 70199868378300
client.clear
client.data["posts"]          # []
client.data.object_id         # 70199868378300

• store and []= write
• fetch and [] read

You can make the service bypass Cistern’s mock data structures by simply creating a self.data function in your service Mock declaration.

class Blog
  include Cistern::Client
  class Mock
    def self.data
      @data ||= {}
    end
  end
end

Working with data

Cistern::Hash contains many useful functions for working with data normalization and transformation.

#stringify_keys

# anywhere
Cistern::Hash.stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
# within a Resource
hash_stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}

#slice

# anywhere
Cistern::Hash.slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
# within a Resource
hash_slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}

#except

# anywhere
Cistern::Hash.except({a: 1, b: 2}, :a) #=> {b: 2}
# within a Resource
hash_except({a: 1, b: 2}, :a) #=> {b: 2}

#except!

# same as #except but modify specified Hash in-place
Cistern::Hash.except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
# within a Resource
hash_except!({:a => 1, :b => 2}, :a) #=> {:b => 2}

Storage

Currently supported storage backends are:

• :hash : Cistern::Hash (default)
• :redis : Cistern::Redis

Backends can be switched by using store_in.

# use redis with defaults
Patient::Mock.store_in(:redis)
# use redis with a specific client
Patient::Mock.store_in(:redis, client: Redis::Namespace.new("cistern", redis: Redis.new(host: "10.1.0.1"))
# use a hash
Patient::Mock.store_in(:hash)

Dirty

Dirty attributes are tracked and cleared when merge_attributes is called.

• changed returns a Hash of changed attributes mapped to there initial value and current value
• dirty_attributes returns Hash of changed attributes with there current value. This should be used in the model save function.

post = Blog::Post.new(id: 1, flavor: "x") # => <#Blog::Post>
post.dirty?           # => false
post.changed          # => {}
post.dirty_attributes # => {}
post.flavor = "y"
post.dirty?           # => true
post.changed          # => {flavor: ["x", "y"]}
post.dirty_attributes # => {flavor: "y"}
post.save
post.dirty?           # => false
post.changed          # => {}
post.dirty_attributes # => {}

Custom Architecture

When configuring your client, you can use :collection, :request, and :model options to define the name of module or class interface for the service component.

For example: if you’d Request is to be used for a model, then the Request component name can be remapped to Demand

For example:

class Blog
  include Cistern::Client.with(interface: :modules, request: "Demand")
end

allows a model named Request to exist

class Blog::Request
  include Blog::Model
  identity :jovi
end

while living on a Demand

class Blog::GetPost
  include Blog::Demand
  def real
    cistern.request.get("/wing")
  end
end

~> 3.0

Request Dispatch

Default request interface passes through #_mock and #_real depending on the client mode.

class Blog::GetPost
  include Blog::Request
  def setup(post_id, parameters)
    [post_id, stringify_keys(parameters)]
  end
  def _mock(*args, **kwargs)
    mock(*setup(*args, **kwargs))
  end
  def _real(post_id, parameters)
    real(*setup(*args, **kwargs))
  end
end

In cistern 3, requests pass through #call in both modes. #dispatch is responsible for determining the mode and
calling the appropriate method.

class Blog::GetPost
  include Blog::Request
  def call(post_id, parameters)
    normalized_parameters = stringify_keys(parameters)
    dispatch(post_id, normalized_parameters)
  end
end

Client definition

Default resource definition is done by inheritance.

class Blog::Post < Blog::Model
end

In cistern 3, resource definition is done by module inclusion.

class Blog::Post
  include Blog::Post
end

Prepare for cistern 3 by using Cistern::Client.with(interface: :module) when defining the client.

class Blog
  include Cistern::Client.with(interface: :module)
end

Examples

• zendesk2
• you_track
• ey-core

Releasing

$ gem bump -trv (major|minor|patch)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request