virtuatable-core 1.0.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaef58986378462da6ff78e3aeac595cbed418f3351254e3e99b303059fe21d1
-  data.tar.gz: 1ed97f4ff856ecfbe5ccf969547ee0141f03f1e9c59304661880f6d4e87bfaf7
+  metadata.gz: dfc5218a02310414bc7961f93e97d05bb37cb73b9d4868fa8c83e6666485447a
+  data.tar.gz: c83d949e50ae999b2182fd7c4678b9b45a5418c25d750d859d43f4f41713029e
 SHA512:
-  metadata.gz: ffc760f437db7e376de09c5e88fa794e440729600819f8cce7474d4db6a122185fc20472020e131ae889d6371f1cf95f0fb7389506ac4ec1f5a9840a3ed2dc98
-  data.tar.gz: '08addb4e9612082536359a2a624f5eded215ba382a8f9b16aebf016cfc35b9c9dbc12a503a3160780dc81896bdabf0434f1966062d5eb339e999eadef92cbec1'
+  metadata.gz: 34d89edd05d094d7db645e4403060bbbe091e3e4c77733285cd34fb7d4ab3890f28a03427bb270195c5422f4ea6235140a5693d5a112b3178f25d7a1fe9e8314
+  data.tar.gz: c5c6871afefd3a2dd445ffaf060c59cb676ed54a720ae26c401af4a5b62e49be4969baac10eebea8bd46ded9a8835249b62168c6ef1338560f00f6d190d288cc

data/lib/core/controllers/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+require 'sinatra/config_file'
+require 'sinatra/custom_logger'
+
+module Core
+  module Controllers
+    # This class represents a base controller for the system, giving access
+    # to checking methods for sessions, gateways, applications, etc.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class Base < Sinatra::Base
+      register Sinatra::ConfigFile
+      helpers Sinatra::CustomLogger
+      # Includes the custom errors throwers and responses helpers.
+      include Core::Helpers::Errors
+      include Core::Helpers::Responses
+      # Includes the checking methods for sessions.
+      include Core::Helpers::Sessions
+      # Include the checkers and getters for OAuth apps
+      include Core::Helpers::Applications
+      # Include checkers for field requirement and check
+      include Core::Helpers::Fields
+      # Include the getter for the currently requested route.
+      include Core::Helpers::Routes
+      # Include the getter and checkers for accounts.
+      include Core::Helpers::Accounts
+      # Include the loading of the parameters from the JSON body
+      include Core::Helpers::Parameters
+      # This module is extended, not included, because it provides routes
+      # declaration methods used in class declarations.
+      extend Core::Helpers::Declarators
+
+      configure do
+        set :logger, Logger.new(STDOUT)
+        logger.level = Logger::ERROR if ENV['RACK_ENV'] == 'test'
+        # This configuration options allow the error handler to work in tests.
+        set :show_exceptions, false
+        set :raise_errors, false
+      end
+
+      error Mongoid::Errors::Validations do |errors|
+        key = errors.document.errors.messages.keys.first
+        message = errors.document.errors.messages[key][0]
+        api_bad_request key, message: message
+      end
+
+      error Core::Helpers::Errors::NotFound do |exception|
+        api_not_found exception.message
+      end
+
+      error Core::Helpers::Errors::BadRequest do |exception|
+        api_bad_request exception.message
+      end
+
+      error Core::Helpers::Errors::Forbidden do |exception|
+        api_forbidden exception.message
+      end
+
+      error StandardError do |error|
+        api_error 500, "unknown_field.#{error.class.name}"
+      end
+    end
+  end
+end

data/lib/core/controllers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Core
+  # Controllers are to be subclassed in each service.
+  # @author Vincent Courtois <courtois.vincent@outlook.com>
+  module Controllers
+    autoload :Base, 'core/controllers/base'
+  end
+end

data/lib/core/helpers/accounts.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # These helpers provide methods used to get and check accounts.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Accounts
+      # Raises a bad request error if the account if not found.
+      # @raise [Virtuatable::API::Errors::BadRequest] the error raised when the account is not found.
+      def account
+        return @account unless @account.nil?
+
+        session_id_required if !respond_to?(:session) || session.nil?
+        @account = session.account
+      end
+
+      def account_id_not_found
+        api_bad_request('session_id.required')
+      end
+    end
+  end
+end

data/lib/core/helpers/applications.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # Helpers to get and check OAuth applications connecting the the application.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Applications
+      # Looks for the application sending the API's request, and raises error if not found.
+      # @param [Core::Models::OAuth::Application] the application requesting the service.
+      def application(premium: false)
+        return @application unless @application.nil?
+
+        check_presence 'app_key'
+        @application = application_model.find_by(key: params['app_key'])
+        api_not_found 'app_key.unknown' if @application.nil?
+        api_forbidden 'app_key.forbidden' if premium && !@application.premium
+
+        @application
+      end
+
+      def application_model
+        Core::Models::OAuth::Application
+      end
+    end
+  end
+end

data/lib/core/helpers/declarators.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # This helpers module is a bit larger than the others as it provides methods
+    # to declare routes whithin a service, performing needed checks and filters.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Declarators
+      # @!attribute [r] routes
+      #   @return [Array<Core::Models::Permissions::Route>] the currently declared routes.
+      attr_reader :api_routes
+
+      # Main method to declare new routes, persisting them in the database and
+      # declaring it in the Sinatra application with the needed before checks.
+      #
+      # @param verb [String] the HTTP method for the route.
+      # @param path [String] the whole URI with parameters for the route.
+      # @param options [Hash] the additional options for the route.
+      def api_route(verb, path, options: {}, &block)
+        options = default_options.merge(options)
+        route = add_route(verb: verb, path: path, options: options)
+
+        # TODO : do everything in the #send itself to avoid
+        # route reload issues when premium is changed. It will
+        # add some treatments but avoid many problems if route.premium
+        send(route.verb, route.path) do
+          application(premium: current_route.premium)
+          session if current_route.authenticated
+          instance_eval(&block)
+        end
+      end
+
+      # Add a route to the database, then to the routes array.
+      # @param verb [String] the HTTP method used to request this route.
+      # @param path [String] the path used to request this route.
+      # @return [Core::Models::Permissions::Route] the created route.
+      def add_route(verb:, path:, options:)
+        route = Core::Models::Permissions::Route.find_or_create_by!(
+          path: path,
+          verb: verb.downcase,
+          premium: options[:premium],
+          authenticated: options[:authenticated]
+        )
+        api_routes.nil? ? @api_routes = [route] : push_route(route)
+        add_permissions(route)
+        route
+      end
+
+      # Pushes the route in the api routes list, by creating it if needed
+      # @param route [Core::Models::Permissions::Route] the route to push in the list of routes.
+      def push_route(route)
+        @api_routes << route if api_routes.none? do |tmp_route|
+          route.id == tmp_route.id
+        end
+      end
+
+      # Add the default access permissions to a route. Any group tagged superuser
+      # can automatically access any newly declared_route.
+      # params route [Core::Models::Permissions::Route] the route to add the permissions to.
+      def add_permissions(route)
+        groups = Core::Models::Permissions::Group.where(is_superuser: true)
+        groups.each do |group|
+          unless route.groups.where(id: group.id).exists?
+            route.groups << group
+            route.save!
+          end
+        end
+      end
+
+      # The default options for a route, being the most used value for each key.
+      # @return [Hash] the default options as a hash.
+      def default_options
+        {
+          # If TRUE the application MUST be premium to access the route.
+          # Mainly used to protect administration routes against illegal accesses.
+          premium: false,
+          # If TRUE the user MUST be authenticated to access the route.
+          authenticated: true
+        }
+      end
+    end
+  end
+end

data/lib/core/helpers/errors/bad_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    module Errors
+      # A bad request error is raised when the data given to a model makes this model invalid.
+      # @author Vincent Courtois <courtois.vincent@outlook.com>
+      class BadRequest < Core::Helpers::Errors::Base
+        def initialize(field:, error:)
+          super(field: field, error: error, status: 400)
+        end
+      end
+    end
+  end
+end

data/lib/core/helpers/errors/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    module Errors
+      # Standard class parent to all specialized http errors.
+      # @author Vincent Courtois <courtois.vincent@outlook.com>
+      class Base < StandardError
+        # @!attribute [rw] field
+        #   @return [String, Symbol] the name of the field in error in the model.
+        attr_accessor :field
+        # @!attribute [rw] action
+        #   @return [String] the name of the action the user was trying to perform on the model (often crate or update).
+        attr_accessor :action
+        # @attribute [rw] error
+        #   @return [String] the label of the error returned by the model.
+        attr_accessor :error
+        # @attribute [rw] status
+        #   @return [Integer] the HTTP status code as a number (eg: 400, 422 or 500)
+        attr_accessor :status
+
+        def initialize(field:, error:, status:)
+          @field = field.to_s
+          @error = error
+          @status = status
+        end
+
+        # Returns the formatted message for this exception.
+        # @return [String] a message indicating what field fails, and why.
+        def message
+          "#{field}.#{error}"
+        end
+      end
+    end
+  end
+end

data/lib/core/helpers/errors/forbidden.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    module Errors
+      # A forbidden error occurs when a user tries to perform an action he's not allowed to.
+      # @author Vincent Courtois <courtois.vincent@outlook.com>
+      class Forbidden < Core::Helpers::Errors::Base
+        def initialize(field:, error:)
+          super(field: field, error: error, status: 403)
+        end
+      end
+    end
+  end
+end

data/lib/core/helpers/errors/not_found.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    module Errors
+      # A not found error occurs when a user tries to reach a resource that does not exist.
+      # @author Vincent Courtois <courtois.vincent@outlook.com>
+      class NotFound < Core::Helpers::Errors::Base
+        def initialize(field:, error:)
+          super(field: field, error: error, status: 404)
+        end
+      end
+    end
+  end
+end

data/lib/core/helpers/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # This module defines method to raise HTTP errors in the routes easily.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Errors
+      autoload :Base, 'core/helpers/errors/base'
+      autoload :BadRequest, 'core/helpers/errors/bad_request'
+      autoload :Forbidden, 'core/helpers/errors/forbidden'
+      autoload :NotFound, 'core/helpers/errors/not_found'
+
+      # Stops the executing and raises an HTTP error in the route.
+      # The message MUST be of the for <field>.<error> to be correctly parsed.
+      # The action is automatically parsed from the route call and added.
+      #
+      # @param status [Integer] the HTTP status code the response will have
+      # @param message [String] the raw message to split and format as body.
+      def api_error(status, message)
+        field, error = message.split('.')
+        docs = settings.errors.try(field).try(error)
+        errors = { status: status, field: field, error: error, docs: docs }
+        halt status, errors.to_json
+      end
+
+      # Stops the execution to return a NOT FOUND response.
+      # @param field [String] the field in params concerned by the error.
+      # @param message [String] the message if different of "unknown".
+      def api_not_found(field, message: 'unknown')
+        api_error 404, "#{field}.#{message}"
+      end
+
+      # Stops the execution to return a BAD REQUEST response.
+      # @param field [String] the field in params concerned by the error.
+      # @param message [String] the message if different of "required".
+      def api_bad_request(field, message: 'required')
+        api_error 400, "#{field}.#{message}"
+      end
+
+      # Stops the execution to return a FORBIDDEN response.
+      # @param field [String] the field in params concerned by the error.
+      # @param message [String] the message if different of "forbidden".
+      def api_forbidden(field, message: 'forbidden')
+        api_error 403, "#{field}.#{message}"
+      end
+    end
+  end
+end

data/lib/core/helpers/fields.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # Helpers for the parameters of a request.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Fields
+      # Checks the presence of several fields given as parameters and halts the execution if it's not present.
+      # @param fields [Array<String>] an array of fields names to search in the parameters
+      def check_presence(*fields)
+        fields.each do |field|
+          api_bad_request "#{field}.required" unless field_defined?(field)
+        end
+      end
+
+      # Checks the presence of either fields given in parameters.
+      # It halts with an error only if ALL parameters are not given.
+      #
+      # @param fields [Array<String>] an array of fields names to search in the parameters
+      # @param key [String] the key to search in the errors configuration file.
+      def check_either_presence(*fields, key:)
+        api_bad_request "#{key}.required" if fields.none? do |field|
+          field_defined?(field)
+        end
+      end
+
+      # Checks if a given field is defined in the params
+      # @param field [String] the name of the field to check in the params
+      # @return [Boolean] TRUE if the field exists, FALSE otherwise.
+      def field_defined?(field)
+        !params.nil? && params.key?(field) && params[field] != ''
+      end
+    end
+  end
+end

data/lib/core/helpers/parameters.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # Helpers to correctly build the parameters hash, even from the JSON body.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Parameters
+      # Returns the parameters depending on whether the request has a body
+      # or not. If it has a body, it parses it, otherwise it just returns the params.
+      # @return [Hash] the parameters sent with the request.
+      def params
+        super.merge(body_params)
+      end
+
+      # The parameters from the JSON body if it is sent.
+      # @return [Hash] the JSON body parsed as a dictionary.
+      def body_params
+        request.body.rewind
+        JSON.parse(request.body.read.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/core/helpers/responses.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # Modules holding the responses that are NOT errors.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Responses
+      # Builds a list of items as a standard API response.
+      # The response will be a JSON hash containing two keys :
+      # - :count will hold the number of items displayed in the list
+      # - :items will hold the list of items.
+      # @param items [Array] the items to format as a standard API response.
+      def api_list(items)
+        halt 200, {
+          count: items.count,
+          items: items.map { |item| enhanced_h(item) }
+        }.to_json
+      end
+
+      # Displays a creation standard response,
+      # returning the informations about the created item.
+      # @param item [Object] any object that responds to #to_h to display to the user.
+      def api_created(item)
+        halt 201, enhanced_json(item)
+      end
+
+      # Displays an item with the standards of the API.
+      # @param item [Object] the item to display as a JSON formatted hash.
+      def api_item(item)
+        halt 200, enhanced_json(item)
+      end
+
+      # Displays a message with a 200 status code
+      # @param message [String] the message to display with the API standards.
+      def api_ok(message)
+        api_item message: message
+      end
+
+      private
+
+      def enhanced_h(item)
+        (item.respond_to?(:enhance) ? item.enhance : item).to_h
+      end
+
+      def enhanced_json(item)
+        enhanced_h(item).to_json
+      end
+    end
+  end
+end

data/lib/core/helpers/routes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # This module provides the #current_route method to get the current
+    # Core::Models::Monitoring::Route object from whithin sinatra routes.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Routes
+      # The currently requested API route, used to see inside the block
+      # if the route is premium or not, authenticated or not.
+      # @return [Core::Models::Monitoring::Route] the currently requested route.
+      def current_route
+        splitted = request.env['sinatra.route'].split(' ')
+        verb = splitted.first.downcase
+        self.class.api_routes.find do |route|
+          route.verb == verb && route.path == splitted.last
+        end
+      end
+    end
+  end
+end

data/lib/core/helpers/sessions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Core
+  module Helpers
+    # This helper gives access to methods about user's session on the API.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    module Sessions
+      # Checks the session of the user requesting the API and returns an error
+      # if it either not exists with the given token, or the token is not given.
+      #
+      # @raise [Virtuatable::API::Errors::NotFound] if the session is not found
+      #   or the token not given in the parameters of the request.
+      # @raise [Virtuatable::API::Errors::BadRequest] if the session token is
+      #   not correctly given in the parameters.
+      #
+      # @return [Core::Models::Authentication::Session] the current session of the user.
+      def session
+        return @session unless @session.nil?
+
+        check_presence 'session_id'
+        @session = session_model.find_by(token: params['session_id'])
+        @session.nil? ? api_not_found('session_id.unknown') : @session
+      end 
+
+      def session_model
+        Core::Models::Authentication::Session
+      end
+    end
+  end
+end

data/lib/core/helpers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Core
+  # The helpers are used inside the controllers to dynamically
+  # add features and functions.
+  # @author Vincent Courtois <courtois.vincent@outlook.com>
+  module Helpers
+    autoload :Accounts, 'core/helpers/accounts'
+    autoload :Applications, 'core/helpers/applications'
+    autoload :Declarators, 'core/helpers/declarators'
+    autoload :Errors, 'core/helpers/errors'
+    autoload :Fields, 'core/helpers/fields'
+    autoload :Parameters, 'core/helpers/parameters'
+    autoload :Responses, 'core/helpers/responses'
+    autoload :Routes, 'core/helpers/routes'
+    autoload :Sessions, 'core/helpers/sessions'
+  end
+end

data/lib/core/models/account.rb

@@ -8,6 +8,8 @@ module Core
       include ActiveModel::SecurePassword
       include Core::Models::Concerns::Enumerable
 
+      store_in collection: 'accounts'
+
       # @!attribute [rw] username
       #   @return [String] the nickname the user chose at subscription, must be given, unique, and 6 or more characters long.
       field :username, type: String
@@ -46,9 +48,6 @@ module Core
       # @!attribute [rw] authorizations
       #   @return [Array<Core::Models::OAuth::Authorization>] the authorization issued by this account to third-party applications to access its data.
       has_many :authorizations, class_name: 'Core::Models::OAuth::Authorization', inverse_of: :account
-      # @!attribute [rw] services
-      #   @return [Array<Core::Models::Monitoring::Service>] the services created by this user.
-      has_many :services, class_name: 'Core::Models::Monitoring::Service', inverse_of: :creator
       # @!attribute [rw] sessions
       #   @return [Array<Core::Models::Authentication::Session>] the sessions on which this account is, or has been logged in.
       has_many :sessions, class_name: 'Core::Models::Authentication::Session', inverse_of: :account
@@ -65,8 +64,6 @@ module Core
       #   @return [Array<Core::Models::Chatrooms::Messages>] all the messages ever sent by the user.
       has_many :messages, class_name: 'Core::Models::Chatrooms::Message', inverse_of: :account
 
-      has_many :memberships, class_name: 'Core::Models::Chatrooms::Membership', inverse_of: :account
-
       # @!attribute [rw] notifications
       #  @return [Array<Core::Models::Notification>] the notifications linked to this user.
       embeds_many :notifications, class_name: 'Core::Models::Notification', inverse_of: :account

data/lib/core/models/authentication/session.rb

@@ -9,6 +9,8 @@ module Core
         include Mongoid::Document
         include Mongoid::Timestamps
 
+        store_in collection: 'sessions'
+
         # @!attribute [rw] token
         #   @return [String] the unique token for this session, used to identify it and be sure the user is connected on this application.
         field :token, type: String

data/lib/core/models/campaign.rb

@@ -6,6 +6,8 @@ module Core
       include Mongoid::Document
       include Mongoid::Timestamps
 
+      store_in collection: 'campaigns'
+
       # @!attribute [rw] title
       #   @return [String] the title, or name, of the campaign, used to identify it in the list.
       field :title, type: String
@@ -14,7 +16,7 @@ module Core
       field :description, type: String
       # @!attribute [rw] is_private
       #   @return [Boolean] TRUE if the campaign can be joined only by being invited by the creator, FALSE if it's publicly displayed and accessible.
-      field :is_private, type: Boolean, default: true
+      field :is_private, type: Mongoid::Boolean, default: true
       # @!attribute [rw] tags
       #   @return [Array<String>] an array of tags describing characteristics of this campaign.
       field :tags, type: Array, default: []
@@ -33,6 +35,10 @@ module Core
       #   @return [Core::Models::Chatrooms::Campaign] the chatroom linked to this campaign.
       embeds_one :chatroom, class_name: 'Core::Models::Chatrooms::Campaign', inverse_of: :campaign
 
+      # @!attribute [rw] tokens
+      #   @return [Array<Core::Models::Campaigns::Token>] the tokens declared in this campaign.
+      embeds_many :tokens, class_name: 'Core::Models::Campaigns::Token', inverse_of: :campaign
+
       # @!attribute [rw] ruleset
       #   @return [Core::Models::Ruleset] the set of rules this campaign is based upon.
       belongs_to :ruleset, class_name: 'Core::Models::Ruleset', inverse_of: :campaigns, optional: true

data/lib/core/models/campaigns/invitation.rb

@@ -13,6 +13,8 @@ module Core
         include Core::Models::Concerns::Enumerable
         include Core::Models::Concerns::Historizable
 
+        store_in collection: 'invitations'
+
         # @!attribute [rw] account
         #   @return [Core::Models::Account] the account the invitation has been issued to.
         belongs_to :account, class_name: 'Core::Models::Account', inverse_of: :invitations

data/lib/core/models/campaigns/map.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Core
+  module Models
+    module Campaigns
+      # A map is a battleground where the players can place tokens and live the adventure.
+      # @author Vincent Courtois <courtois.vincent@outlook.com>
+      class Map
+        include Mongoid::Document
+        include Mongoid::Timestamps
+
+        store_in collection: 'maps'
+
+        # @!attribute [rw] height
+        #   @return [Integer] the number of lines in the map matric.
+        field :height, type: Integer, default: 1
+        # @!attribute [rw] width
+        #   @return [Integer] the number of columns in the map matric.
+        field :width, type: Integer, default: 1
+
+        # @!attribute [rw] campaign
+        #   @return [Core::Models::Campaign] the campaign in which the map can be found.
+        belongs_to :campaign, class_name: 'Core::Models::Campaign', inverse_of: :maps
+
+        # @!attribute [rw] positions
+        #   @return [Array<Core::Model::Campaigns::TokenPosition>] the instanciated tokens on this map.
+        embeds_many :positions, class_name: 'Core::Models::Campaigns::TokenPosition', inverse_of: :map
+
+        validates :height,
+          numericality: { greater_than: 0, message: 'minimum' }
+        
+        validates :width,
+          numericality: { greater_than: 0, message: 'minimum' }
+      end
+    end
+  end
+end

data/lib/core/models/campaigns/tag.rb

@@ -9,6 +9,8 @@ module Core
         include Mongoid::Document
         include Mongoid::Timestamps
 
+        store_in collection: 'tags'
+
         # @!attribute [rw] content
         #   @return [String] the string content of the tag, describing a characteristic.
         field :content, type: String