tramway-api 1.0.2.2 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 408807959271db1306b9048f9aaf1d210ae2f8e1b4d1c364789bb706112aa5a9
-  data.tar.gz: 3b169249d7fd04aefbb3fb7d777f2a8f6f5a163046978e780001f009fb2df77f
+  metadata.gz: 4e41e964d3ade1c230c77385929ee24692558d8cf59571134ccd9da815db2295
+  data.tar.gz: 9dc5042350b5a9deb0e2afda435797bec9015743eaa5bb0f184aaaa1ccfcbb21
 SHA512:
-  metadata.gz: 7e42a01f15193f7a3617f3c4af061fc7959cdc319ab4e0cc81f97ef5fd6322c13a31eb4ccc8ffc3f53936fd41cc56360ce1d67ef19ecb0b9b02b2c567e85a638
-  data.tar.gz: 1b14778d781bb1f0343f7984c426e382066e7e9add7af4d833632259ce96c1fcade765e97a6f4cd9acf147a368a12d9c85cef6f75b7a8cd7dc9c335e4b40a1b8
+  metadata.gz: 7627d0d269ff690cddc29a5a78369f968701e3992cb53e0b1f7c5b61d7e9e2b99e7a5af343dd5266e762bc5aa786ecfb06573128930360279e98f1ed1f7fce7f
+  data.tar.gz: ddebade027114042a877ff9a19a531bedd8787317bd8b3065b630a7fff9ba062262bfc719d94dc81bd514b9f4fef6790e46a34566510aa424db94421de362712

data/README.md

@@ -1,26 +1,287 @@
 # Tramway::Api
-Short description and motivation.
+
+## English Readme
+
+coming soon...
+
+## Russian Readme
+
+Простой в использовании, легко устанавливаемый и плохо кастомизируемый Rails-engine с готовым CRUD через API.
+
+Принцип работы. В приложении заранее указывается для каких моделей создаётся API CRUD. Идея проекта - возможность быстрой выкатки API, с возможностью в последствии избавиться от Tramway API, когда ваш проект становится сложнее.
+
+Гем НЕ манкипатчит стандартные классы и поведение Rails! Именно по этой причине было решено реализовать как Rails-engine, который в последствии можно просто и легко удалить из проекта.
+
+Фичи:
+
+* готовый CRUD для определённых разработчиком моделей
+* сохранение истории изменений записей (используется гем `audited`)
+* поддержка загрузки файлов (используется `carrierwave`)
+* аутентификация пользователя через JWT (используется `knock`)
+* поддержка по умолчанию JSON API спецификации (через гем `active_model_serializers`)
+* мягкое удаление записей по умолчанию
+* поддержка коммуникации по уникальному uid объектов, чтобы не публиковать ID в базе
+
+Ограничения:
+
+* только с ActiveRecord
+* только с версией Rails 5.1.* (поддержка 5.2 вскоре будет реализована автором гема, поддержка автором Rails 6 начнётся с версии 6.1. По религиозным автор не использует Rails версий *.0.*
+* Ruby >= 2.3
+* все модели, которые будут использованы гемом должны наследоваться от `Tramway::Core::ApplicationRecord`
+* все модели, которые будут использованы гемом должны иметь атрибут `state`, типа `string` или `text`. Этот атрибут нужен для реализации мягкого удаления. Полное удаление записей из базы не поддерживается
+* все модели, которые будут использованы гемом должны иметь атрибут 
+
+Недостатки, которые будут вскоре ликвидированы:
+
+* ядро `tramway-core` подгружает в себя ненужных для API гемов (недостаток не имеет смысла в случае использования вместе с этим решением гема `tramway-admin`):
+  * bootstrap
+  * font_awesome5_rails
+  * haml
+* требуется ручное добавление требуемых для работы гемов
+  ```ruby
+  gem 'active_model_serializers', '0.10.5'
+  gem 'tramway-core'
+  gem 'state_machine', github: 'seuros/state_machine'
+  gem 'knock'
+  ```
 
 ## Usage
-How to use my plugin.
 
-## Installation
-Add this line to your application's Gemfile:
+```
+rails new tramway_api_sample
+```
+
+*Gemfile*
+
+```ruby
+gem 'tramway-api', '>= 1.1.0.1'
+gem 'active_model_serializers', '0.10.5'
+gem 'tramway-core'
+gem 'state_machine', github: 'seuros/state_machine'
+gem 'knock'
+```
+
+Run `bundle install`
+
+Then generate User (you use another name, it's just an example) model
+
+```
+rails g model user email:text password_digest:text username:text state:text uid:text
+```
+
+Add generating uid by default
+
+*db/migrate/create_users_*.rb
+
+```ruby
+t.uuid :uid, default: 'uuid_generate_v4()'
+```
+
+*app/models/user.rb*
+
+```ruby
+class User < Tramway::Core::ApplicationRecord
+  has_secure_password
+end
+```
+
+Create file `config/initializers/tramway.rb`
+
+```ruby
+::Tramway::Api.auth_config = { user_model: User, auth_attributes: %i[email username] }
+::Tramway::Api.set_available_models user: %i[create update]
+```
+
+Run `rails g tramway:core:install`
+
+Run `rails db:create db:migrate`
+
+*config/routes.rb*
+
+```ruby
+Rails.application.routes.draw do
+  mount Tramway::Api::Engine, at: '/api'
+end
+```
+
+Create file *app/forms/user_sign_up_form.rb*
+
+```ruby
+class UserSignUpForm < Tramway::Core::ApplicationForm
+  properties :username, :email, :password
+end
+```
+
+**DONE!**
+
+## Testing
+
+# Preparation (optional)
+
+Let's write RSpec test to check what we have:
+
+*Gemfile*
 
 ```ruby
-gem 'tramway-api'
+group :test do
+  gem 'rspec-rails', '~> 3.5'
+  gem 'rspec-json_expectations', '2.2.0'
+  gem 'factory_bot_rails', '~> 4.0'
+  gem 'json_matchers'
+  gem 'json_api_test_helpers', '1.1.1'
+end
 ```
 
-And then execute:
-```bash
-$ bundle
+Run `bundle install`
+
+Run `RAILS_ENV=test rails db:create db:migrate`
+
+Run `mkdir spec`
+
+Create file `spec/spec_helper.rb` with:
+
+```ruby
+ENV['RAILS_ENV'] ||= 'test'
+require File.expand_path('../config/environment', __dir__)
+require 'rspec/rails'
+require 'rspec/autorun'
+require 'rspec/expectations'
+require 'rspec/json_expectations'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install tramway-api
+Create file `spec/rails_helper.rb` with:
+
+```ruby
+require 'spec_helper'
+require 'factory_bot'
+require 'rspec/rails'
+require 'rspec/json_expectations'
+require 'json_matchers/rspec'
+require 'json_api_test_helpers'
+require 'rake'
+
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+  config.include RSpec::Rails::RequestExampleGroup, type: :feature
+  config.include JsonApiTestHelpers
+end
 ```
 
+# SignUp user
+
+Create file `spec/tramway_api_spec.rb` with:
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe 'Post creating user', type: :feature do
+  describe 'POST /api/v1/user with model User' do
+    let(:attributes) { attributes_for :user }
+
+    it 'returns created status' do
+      post '/api/v1/user', params: { user: attributes }
+      expect(response.status).to eq 201
+    end
+    
+    it 'returns no errors' do
+      post '/api/v1/user', params: { user: attributes }
+
+      expect(json_response[:response]). to be_nil
+    end
+  end
+end
+```
+
+# SignIn User
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe 'Post generate token', type: :feature do
+  describe 'POST /api/v1/user_token' do
+    let(:user) { create :user, password: '123456789' }
+
+    it 'returns created status' do
+      post '/api/v1/user_token', params: { auth: { login: user.email, password: '123456789' }  }
+
+      expect(response.status).to eq 201
+    end
+    
+    it 'returns token' do
+      post '/api/v1/user_token', params: { auth: { login: user.email, password: '123456789' }  }
+
+      expect(json_response[:auth_token].present?).to be_truthy
+      expect(json_response[:user]).to include_json({ email: user.email, uid: user.uid })
+    end
+
+  end
+end
+
+```
+
+Run `rspec` to test
+
+We have route `user`, which create new authenticable user.
+
+For other models we have route `records`.
+
+```
+~: rails routes
+     Prefix Verb URI Pattern Controller#Action
+tramway_api      /api        Tramway::Api::Engine
+
+Routes for Tramway::Api::Engine:
+ v1_user_token POST   /v1/user_token(.:format)       tramway/api/v1/user_tokens#create
+       v1_user GET    /v1/user(.:format)             tramway/api/v1/users#show
+               POST   /v1/user(.:format)             tramway/api/v1/users#create
+    v1_records GET    /v1/records(.:format)          tramway/api/v1/records#index
+               POST   /v1/records(.:format)          tramway/api/v1/records#create
+ new_v1_record GET    /v1/records/new(.:format)      tramway/api/v1/records#new
+edit_v1_record GET    /v1/records/:id/edit(.:format) tramway/api/v1/records#edit
+     v1_record GET    /v1/records/:id(.:format)      tramway/api/v1/records#show
+               PATCH  /v1/records/:id(.:format)      tramway/api/v1/records#update
+               PUT    /v1/records/:id(.:format)      tramway/api/v1/records#update
+               DELETE /v1/records/:id(.:format)      tramway/api/v1/records#destroy
+
+```
+
+## Methods
+
+### Initializer methods
+
+#### auth_config
+
+Sets default ActiveRecord model, which used as main user to be authenticated with JWT.
+
+`user_model` - model name
+`auth_attributes` - array of available attributes used as login. 
+
+this model must have field `password_digest`, because we use `bcrypt` gem for authentication (providing other name of password attribute instead of `password` is coming soon)
+
+### set_available_models
+
+Sets ActiveRecord models which will be used in API
+
+Argument is a hash. Keys are underscored models names, values are arrays of available methods for every model.
+
+Enabled methods:
+
+* create
+* update
+* show
+* index
+* destroy
+
+
 ## Contributing
 Contribution directions go here.
 

data/app/controllers/tramway/api/application_controller.rb

@@ -1,7 +1,7 @@
 module Tramway
   module Api
     class ApplicationController < ::Tramway::Core::ApplicationController
-      include Knock::Authenticable
+      include ::Knock::Authenticable
       protect_from_forgery with: :null_session, if: proc { |c| c.request.format == 'application/json' }
       rescue_from ActiveRecord::RecordNotFound, with: :not_found
 
@@ -23,9 +23,9 @@ module Tramway
 
       def auth_token
         if entity.respond_to? :to_token_payload
-          Knock::AuthToken.new payload: entity.to_token_payload
+          ::Knock::AuthToken.new payload: entity.to_token_payload
         else
-          Knock::AuthToken.new payload: { sub: entity.id }
+          ::Knock::AuthToken.new payload: { sub: entity.id }
         end
       end
 
@@ -34,12 +34,20 @@ module Tramway
           if Tramway::Api.user_based_model.respond_to? :from_token_request
             Tramway::Api.user_based_model.active.from_token_request request
           else
-            params[:auth] && Tramway::Api.user_based_model.active.find_by(email: auth_params[:email])
+            params[:auth] && find_user_by_auth_attributes
           end
       end
 
+      def find_user_by_auth_attributes
+        Tramway::Api.auth_attributes.each do |attribute|
+          object = Tramway::Api.user_based_model.active.where.not(attribute => nil).find_by(attribute => auth_params[:login])
+          return object if object
+        end
+        nil
+      end
+
       def auth_params
-        params[:auth]&.permit :email, :password
+        params[:auth]&.permit(:login, :password)
       end
     end
   end

data/app/controllers/tramway/api/v1/records_controller.rb

@@ -2,6 +2,7 @@ module Tramway::Api::V1
   class RecordsController < ::Tramway::Api::V1::ApplicationController
     before_action :check_available_model_class
     before_action :check_available_model_action
+    before_action :authenticate_user
 
     def index
       records = model_class.active.order(id: :desc).send params[:scope] || :all
@@ -22,7 +23,7 @@ module Tramway::Api::V1
     end
 
     def update
-      record_form = form_class.new model_class.find params[:id]
+      record_form = form_class.new model_class.active.find params[:id]
       if record_form.submit params[:data][:attributes]
         render json: record_form.model,
           serializer: serializer_class,
@@ -32,6 +33,13 @@ module Tramway::Api::V1
       end
     end
 
+    def show
+      record = model_class.active.find params[:id]
+      render json: record,
+        serializer: serializer_class,
+        status: :ok
+    end
+
     private
 
     def check_available_model_class

data/app/controllers/tramway/api/v1/users_controller.rb

@@ -5,7 +5,8 @@ class Tramway::Api::V1::UsersController < ::Tramway::Api::V1::ApplicationControl
   include Tramway::ClassNameHelpers
 
   def create
-    user_form = form_class_name(Tramway::Api.user_based_model).new Tramway::Api.user_based_model.new
+    user_form = sign_up_form_class_name(Tramway::Api.user_based_model).new Tramway::Api.user_based_model.new
+    # Implement JSON API spec here
     if user_form.submit params[Tramway::Api.user_based_model.name.underscore]
       token = ::Knock::AuthToken.new(payload: { sub: user_form.model.id }).token
       # FIXME refactor this bullshit
@@ -24,4 +25,10 @@ class Tramway::Api::V1::UsersController < ::Tramway::Api::V1::ApplicationControl
   def show
     render json: current_user, status: :ok
   end
+
+  private
+
+  def sign_up_form_class_name(model_class)
+    form_class_name "#{model_class}SignUp"
+  end
 end

data/lib/tramway/api.rb

@@ -3,12 +3,20 @@ require 'tramway/api/engine'
 module Tramway
   module Api
     class << self
+      def auth_config
+        @@auth_config ||= { user_model: ::Tramway::User::User, auth_attributes: :email }
+      end
+
+      def auth_config=(**params)
+        @@auth_config = params
+      end
+
       def user_based_model
-        @@user_based_model ||= ::Tramway::User::User
+        @@auth_config[:user_model]
       end
 
-      def user_based_model=(model_class)
-        @@user_based_model = model_class
+      def auth_attributes
+        @@auth_config[:auth_attributes]
       end
 
       def set_available_models(**models)

data/lib/tramway/api/version.rb

@@ -1,5 +1,5 @@
 module Tramway
   module Api
-    VERSION = '1.0.2.2'
+    VERSION = '1.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tramway-api
 version: !ruby/object:Gem::Version
-  version: 1.0.2.2
+  version: '1.2'
 platform: ruby
 authors:
 - Pavel Kalashnikov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-02 00:00:00.000000000 Z
+date: 2019-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: knock
@@ -99,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Engine for api