ocean-rails 1.14.0

data/lib/ocean/api_resource.rb

@@ -0,0 +1,135 @@
+module ApiResource
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+
+  module ClassMethods
+
+    #
+    # This method implements the common behaviour in Ocean for requesting collections
+    # of resources, including conditions, +GROUP+ and substring searches. It can be used
+    # directly on a class:
+    #
+    #  @collection = ApiUser.collection(params)
+    #
+    # or on any Relation:
+    #
+    #  @collection = @api_user.groups.collection(params)
+    #
+    # Since a Relation is returned, further chaining is possible:
+    #
+    #  @collection = @api_user.groups.collection(params).active.order("email ASC")
+    #
+    # The whole params hash can safely be passed as the input arg: keys are filtered so 
+    # that matches only are done against the attributes declared in the controller using 
+    # +ocean_resource_model+.
+    #
+    # The +group:+ keyword arg, if present, adds a +GROUP+ clause to the generated SQL.
+    #
+    # The +search:+ keyword arg, if present, searches for the value in the database string or
+    # text column declared in the controller's +ocean_resource_model+ declaration.
+    # The search is done using an SQL +LIKE+ clause, with the substring framed by 
+    # wildcard characters. It's self-evident that this is not an efficient search method
+    # for larger datasets; in such cases, other search methods should be employed.
+    #
+    # If +page:+ is present, pagination will be added. If +page+ is less than zero, an
+    # empty Relation will be returned. Otherwise, +page_size:+ (default 25) will be used
+    # to calculate OFFSET and LIMIT. The default +page_size+ for a resource class can
+    # also be declared using +ocean_resource_model+.
+    #
+    def collection(bag={})
+      collection_internal bag, bag[:group], bag[:search], bag[:page], bag[:page_size]
+    end
+
+
+    def collection_internal(conds={}, group, search, page, page_size)
+      if index_only != []
+        new_conds = {}
+        index_only.each { |key| new_conds[key] = conds[key] if conds[key].present? }
+        conds = new_conds
+      end
+      # Fold in the conditions
+      query = all.where(conds)
+      # Take care of grouping
+      query = query.group(group) if group.present? && index_only.include?(group.to_sym)
+      # Searching
+      if search.present?
+        return query.none if index_search_property.blank?
+        query = query.where("#{index_search_property} LIKE ?", "%#{search}%")
+      end
+      # Pagination
+      if page.present?
+        return query.none if page < 0
+        query = query.limit(page_size || collection_page_size).offset(page_size * page)
+      end
+      # Finally, return the accumulated Relation
+      query
+    end
+
+
+    #
+    # Returns the latest version for the resource class. E.g.:
+    #
+    #  > ApiUser.latest_version
+    #  "v1"
+    #
+    def latest_api_version
+      Api.version_for(self.class.name.pluralize.underscore)
+    end
+
+    #
+    # Invalidate all members of this class in Varnish using a +BAN+ requests to all
+    # caches in the Chef environment. The +BAN+ requests are done in parallel.
+    # The number of +BAN+ requests, and the exact +URI+ composition in each request,
+    # is determined by the +invalidate_collection:+ arg to the +ocean_resource_model+
+    # declaration in the model.
+    #
+    def invalidate
+      resource_name = name.pluralize.underscore
+      varnish_invalidate_collection.each do |suffix|
+        Api.ban "/v[0-9]+/#{resource_name}#{suffix}"
+      end
+    end
+
+  end
+
+
+  # Instance methods
+
+  #
+  # Convenience function used to touch two resources in one call, e.g:
+  #
+  #  @api_user.touch_both(@connectee)
+  #
+  def touch_both(other)
+    touch
+    other.touch
+  end
+
+
+  #
+  # Invalidate the member and all its collections in Varnish using a +BAN+ requests to all
+  # caches in the Chef environment. The +BAN+ request are done in parallel.
+  # The number of +BAN+ requests, and the exact +URI+ composition in each request,
+  # is determined by the +invalidate_member:+ arg to the +ocean_resource_model+
+  # declaration in the model.
+  #
+  # The optional arg +avoid_self+, if true (the default is false), avoids invalidating
+  # the basic resource itself: only its derived collections are invalidated. This is useful
+  # when instantiating a new resource.
+  #
+  def invalidate(avoid_self=false)
+    self.class.invalidate
+    resource_name = self.class.name.pluralize.underscore
+    varnish_invalidate_member.each do |thing|
+      if thing.is_a?(String)
+        Api.ban "/v[0-9]+/#{resource_name}/#{self.id}#{thing}" if !avoid_self
+      else
+        Api.ban "/v[0-9]+/#{thing.call(self)}"
+      end
+    end
+  end
+
+end

data/lib/ocean/flooding.rb

@@ -0,0 +1,29 @@
+# # Rack::Attack.blacklist('block 1.2.3.4') do |req|
+# #   true
+# # end
+
+# Rack::Attack.blacklisted_response = lambda do |env|
+#   [ 403, {}, ['Blacklisted']]
+# end
+
+
+# Rack::Attack.throttle('req/ip', :limit => 1000, :period => 1.second) do |req|
+#   # If the return value is truthy, the cache key for the return value
+#   # is incremented and compared with the limit. In this case:
+#   #   "rack::attack:#{Time.now.to_i/1.second}:req/ip:#{req.ip}"
+#   # We might want to use the token value instead of the #{req.ip} value.
+#   # (IPs may be shared, tokens never are.)
+#   #
+#   # If falsy, the cache key is neither incremented nor checked.
+#   req.ip
+# end
+
+# Rack::Attack.throttled_response = lambda do |env|
+#   allowed =     env['rack.attack.match_data'][:limit]
+#   t =           env['rack.attack.match_data'][:period].inspect
+#   made =        env['rack.attack.match_data'][:count]
+#   retry_after = env['rack.attack.match_data'][:period] rescue nil
+#   [ 429, 
+#     {'Retry-After' => retry_after.to_s}, 
+#     ["Too Many Requests. You have exceeded your quota of #{allowed} request(s)/#{t} by #{made - allowed}."]]
+# end

data/lib/ocean/ocean_application_controller.rb

@@ -0,0 +1,214 @@
+module OceanApplicationController
+
+  #
+  # Sets the default URL generation options to the HTTPS protocol, and
+  # the host to the OCEAN_API_HOST, that is, to the external URL of the
+  # Ocean API. We always generate external URIs, even for internal calls.
+  # It's the responsibility of the other service to rewrite external
+  # to internal URIs when calling the internal API point.
+  #
+  def default_url_options(options = nil)
+    { :protocol => "https", :host => OCEAN_API_HOST }
+  end
+  
+  
+  #
+  # Ensures that there is an +X-API-Token+ HTTP header in the request.
+  # Stores the token in @x_api_token for use during authorisation of the
+  # current controller action. If there's no +X-API-Token+ header, the
+  # request is aborted and an API error with status 400 is returned.
+  #
+  # 400 error responses will always contain a body with error information
+  # explaining the API error:
+  #
+  #  {"_api_error": ["X-API-Token missing"]}
+  #
+  # or
+  #
+  #  {"_api_error": ["Authentication expired"]}
+  #
+  def require_x_api_token
+    return true if ENV['NO_OCEAN_AUTH']
+    @x_api_token = request.headers['X-API-Token']
+    return true if @x_api_token.present?
+    logger.info "X-API-Token missing"
+    render_api_error 400, "X-API-Token missing"
+    false
+  end
+  
+
+
+  #
+  # Class variable to hold any extra controller actions defined in the
+  # +ocean_resource_controller+ declaration in the resource controller.
+  #
+  @@extra_actions = {}
+
+
+  #
+  # Performs authorisation of the current action. Returns true if allowed,
+  # false if not. Calls the Auth service using a +GET+, which means previous
+  # authorisations using the same token and args will be cached in Varnish.
+  #
+  def authorize_action
+    return true if ENV['NO_OCEAN_AUTH']
+    # Obtain any nonstandard actions
+    @@extra_actions[controller_name] ||= begin
+      extra_actions
+    rescue NameError => e
+      {}
+    end
+    # Create a query string and call Auth
+    qs = Api.authorization_string(@@extra_actions, controller_name, action_name)
+    response = Api.permitted?(@x_api_token, query: qs)                                   
+    if response.status == 200
+      @auth_api_user_id = response.body['authentication']['user_id']  # Deprecate and remove
+      @auth_api_user_uri = response.body['authentication']['_links']['creator']['href']  # Keep
+      return true
+    end
+    error_messages = response.body['_api_error']
+    render_api_error response.status, *error_messages
+    false
+  end
+
+  
+  #
+  # Updates +created_by+ and +updated_by+ to the ApiUser for which the current request
+  # is authorised. The attributes can be declared either String (recommended) or
+  # Integer (deprecated). If String, they will be set to the URI of the ApiUser. (If
+  # Integer, to their internal SQL ID.)
+  #
+  def set_updater(obj)
+    id_or_uri = obj.created_by.is_a?(Integer) ? @auth_api_user_id : @auth_api_user_uri
+    obj.created_by = id_or_uri if obj.created_by.blank? || obj.created_by == 0
+    obj.updated_by = id_or_uri
+  end
+  
+  
+  #
+  # Renders an API level error. The body will be a JSON hash with a single key, 
+  # +_api_error+. The value is an array containing the +messages+.
+  #
+  #  render_api_error(500, "An unforeseen error occurred")
+  #
+  # results in a response with HTTP status 500 and the following body:
+  #
+  #  {"_api_error": ["An unforeseen error occurred"]}
+  #
+  # Resource consumers should always examine the body when an error is returned,
+  # as +_api_error+ always will give additional information which may be required
+  # to process the error properly.
+  #
+  def render_api_error(status_code, *messages)
+    render json: {_api_error: messages}, status: status_code
+  end
+  
+  #
+  # Renders a +HEAD+ response with HTTP status 204 No Content.
+  #
+  def render_head_204
+    render text: '', status: 204, content_type: 'application/json'
+  end
+  
+  #
+  # Renders a HTTP 422 Unprocessable Entity response with a body enumerating
+  # each invalid Rails resource attribute and all their errors. This is usually
+  # done in response to detecting a resource is invalid during +POST+ (create) and
+  # +PUT/PATCH+ (update). E.g.:
+  #
+  #  {"name": ["must be specified"],
+  #   "email": ["must be specified", "must contain a @ character"]}
+  #
+  # The messages are intended for presentation to an end user.
+  #
+  def render_validation_errors(r)
+    render json: r.errors, :status => 422
+  end
+  
+  #
+  # This is the main rendering function in Ocean. The argument +x+ can be a resource
+  # or a collection of resources (which need not be of the same type).
+  #
+  # The keyword arg +new+, if true, sets the response HTTP status to 201 and also adds
+  # a +Location+ HTTP header with the URI of the resource.
+  #
+  # Rendering is done using partials only. These should by convention be located in
+  # their standard position, begin with an underscore, etc. The +ocean+ gem generator
+  # for resources creates a partial in the proper location.
+  #
+  def api_render(x, new: false)
+    if !x.is_a?(Array) && !x.is_a?(ActiveRecord::Relation)
+      partial = x.to_partial_path
+      if new
+        render partial: partial, object: x, status: 201, location: x
+      else
+        render partial: partial, object: x
+      end
+      return
+    elsif x == []
+      render text: '[]'
+      return
+    else
+      partials = x.collect { |m| render_to_string(partial: m.to_partial_path, 
+                                                  locals: {m.class.model_name.i18n_key => m}) }
+      render text: '[' + partials.join(',') + ']'
+    end
+  end
+
+
+  #
+  # Filters away all non-accessible attributes from params. Thus, we still are
+  # using pre-Rails 4.0 protected attributes. This will eventually be replaced
+  # by strong parameters. Takes a class and returns a new hash containing only
+  # the model attributes which may be modified.
+  #
+  def filtered_params(klass)
+    result = {}
+    params.each do |k, v| 
+      result[k] = v if klass.accessible_attributes.include?(k)
+    end
+    result
+  end
+
+
+  #
+  # Cache values for collections. Accepts a class or a scope. The cache value
+  # is based on three components: (1) the name of the class, (2) the number of 
+  # members in the collection, and (3) the modification time of the last updated 
+  # member.
+  #
+  def collection_etag(coll)
+    coll.name.constantize # Force a load of the class (for secondary collections)
+    last_updated = coll.order(:updated_at).last.updated_at.utc rescue 0
+    # We could also, in the absence of an updated_at attribute, use created_at.
+    { etag: "#{coll.name}:#{coll.count}:#{last_updated}"
+    }
+  end
+
+
+  #
+  # This method finds the other resource for connect/disconnect, given the
+  # value of the param +href+, which should be a complete resource URI.
+  #
+  # Renders API errors if the +href+ arg is missing, can't be parsed, or
+  # the resource can't be found.
+  #
+  # Sets @connectee_class to the class of the resource pointed to by +href+,
+  # and @connectee to the resource itself.
+  #
+  def find_connectee
+    href = params[:href]
+    render_api_error(422, "href query arg is missing") and return if href.blank?
+    begin
+      routing = Rails.application.routes.recognize_path(href)
+    rescue ActionController::RoutingError
+      render_api_error(422, "href query arg isn't parseable")
+      return
+    end
+    @connectee_class = routing[:controller].classify.constantize
+    @connectee = @connectee_class.find_by_id(routing[:id])
+    render_api_error(404, "Resource to connect not found") and return unless @connectee
+    true
+  end
+
+end

data/lib/ocean/ocean_resource_controller.rb

@@ -0,0 +1,76 @@
+#
+# This is an "acts_as" type method to be used in ActiveRecord model
+# definitions: "ocean_resource_controller".
+#
+
+module Ocean
+  module OceanResourceController
+    
+    extend ActiveSupport::Concern
+
+    included do
+    end
+
+    module ClassMethods
+
+      #
+      # The presence of +ocean_resource_controller+ in a Rails controller declares
+      # that the controller is an Ocean controller handling an Ocean resource. It takes
+      # two keyword parameters:
+      #
+      # +required_attributes+: a list of keywords naming model attributes which must be
+      # present in every update operation. If an API consumer submits data where any
+      # of these attributes isn't present, an API error will be generated.
+      #
+      #   ocean_resource_controller required_attributes: [:lock_version, :title]
+      #
+      # +extra_actions+: a hash containing information about extra controller actions
+      # apart from the standard Rails ones of +index+, +show+, +create+, +update+, and 
+      # +destroy+. One entry per extra action is required in order to process authentication
+      # requests. Here's an example:
+      #
+      #   ocean_resource_controller extra_actions: {'comments' =>       ['comments', "GET"],
+      #                                             'comment_create' => ['comments', "POST"]}
+      #
+      # The above example declares that the controller has two non-standard actions called
+      # +comments+ and +comments_create+, respectively. Their respective values indicate that
+      # +comments+ will be called as the result of a +GET+ to the +comments+ hyperlink, and
+      # that +comment_create+ will be called as the result of a +POST+ to the same hyperlink.
+      # Thus, +extra_actions+ maps actions to hyperlink names and HTTP methods.
+      #
+      def ocean_resource_controller(required_attributes: [:lock_version, :name, :description],
+                                    extra_actions:       {}
+      	                           )
+      	cattr_accessor :ocean_resource_controller_extra_actions
+      	cattr_accessor :ocean_resource_controller_required_attributes
+      	self.ocean_resource_controller_extra_actions = extra_actions
+      	self.ocean_resource_controller_required_attributes = required_attributes
+      end
+    end
+
+
+    #
+    # Used in controller code internals to obtain the extra actions declared using
+    # +ocean_resource_controller+.
+    #
+    def extra_actions
+      self.class.ocean_resource_controller_extra_actions
+    end
+
+
+    #
+    # Returns true if the params hash lacks a required attribute declared using
+    # +ocean_resource_controller+.
+    #
+    def missing_attributes?
+      self.class.ocean_resource_controller_required_attributes.each do |attr|
+        return true unless params[attr]
+      end
+      return false
+    end
+
+  end
+end
+
+
+ActionController::Base.send :include, Ocean::OceanResourceController