Apiway — новый способ клиент-серверной транспортировки данных

Клиент

# сохранение значения в хранилище
client[:user_id] = 1

# получение значения из хранилища
client[:user_id] # > 1

module Apiway
  class Client

    on_connected do
      # ваш код обработки подключения нового клиента
      # например можно увеличить счетчик онлайна
    end

    on_message do |message|
      # тут можно обработать любое входящее сообщение
    end

    on_disconnected do
      # ваш код обработки отключения нового клиента
      # а здесь счетчик онлайна можно уменьшить
    end

  end
end

Модель

class Test < ActiveRecord::Base

  include Apiway::Model

end

Контроллер

class UsersController < ApplicationController

  include Apiway::Controller

  # Фильтры аналогичны фильтрам в Rails

  # Before-фильтры

  before_action :method_name
  before_action :method_name, only:   :action_name
  before_action :method_name, only:   [ :action_name, :action_name ]
  before_action :method_name, except: :action_name
  before_action :method_name, except: [ :action_name, :action_name ]

  # After-фильтры

  after_action  :method_name
  after_action  :method_name, only:   :action_name
  after_action  :method_name, only:   [ :action_name, :action_name ]
  after_action  :method_name, except: :action_name
  after_action  :method_name, except: [ :action_name, :action_name ]

  # Определение экшена

  action :auth do
    # данный экшен запустится при вызове с клиента 
    # Api.query("Users.auth", {name: "Bob", pass: "querty"})
    #    .then(function( id ){ console.log("User id: ", id) })
    #    .catch(function( e ){ console.log("Error: ", e) })
    begin
      # метод params будет возвращать хэш переданных параметров
      user = User.find_by! name: params[ :name ], pass: params[ :pass ]
    rescue Exception => e
      # если юзер с указанным именем и паролем не найден, то метод error
      # остановит дальнейшее выполнение экшена и обещание на клиенте 
      # завершится неудачей, в консоли появится "Error: auth_error"
      error :auth_error
      # метод error можно вызывать и в фильтрах, тогда, например, при
      # вызове его в before-фильтре, экшен не запустится вообще и 
      # обещание на клиенте также завершится неудачей
    else
      # иначе с помощью метода client мы можем получить текущего
      # клиента (экземпляр Apiway::Client), и сохранить в его хранилище
      # id пользователя
      client[:user_id] = user.id
      # обещание на клиенте завершится успехом и в качестве параметров
      # будет передан результат работы экшена, в данном случае это будет id
      # в консоли появится "User id: 1"
    end
  end

end

Ресурс

# Данный ресурс будет открываться на клиенте следующим образом
# var userMessages = new Resource("UserMessages", {limit: 30});
# userMessages.onChange(function( data ){ console.log("New data", data) });
# userMessages.onError(function( e ){ console.log("Error", e) });
class UserMessagesResource < ApplicationResource

  include Apiway::Resource

  # Определение зависимостей
  depend_on Message, User
  # здесь мы указываем, что данные ресурса зависят от моделей Message и User, 
  # если в этих моделях произойдут изменения, то ресурс автоматически 
  # синхронизирует свои данные

  # Доступ к данным ресурса
  access do
    # данный код будет выполняться каждый раз перед синхронизацией данных ресурса
    # метод client также, как и в контроллере возвращает текущего клиента,
    # из хранилища которого мы можем получить значение :user_id
    error :auth_error unless client[:user_id]
    # вызов метода error предотвратит синхронизацию а клиентский ресурс сгенерирует 
    # событие "error" с параметром "auth_error", в консоли браузера
    # появится "Error: auth_error" при этом, ресурс останется "живым",
    # но "закрытым" и, как только клиент авторизуется, ресурс автоматически 
    # откроется и сгенерирует событие событие "change" с новыми данными
    # в консоли браузера появится "New data: [{mgs},{mgs},{mgs}...]"
  end

  # Определение возвращаемых данных
  # данный код должен быть построен так, чтобы в любой момент времени
  # возвращать актуальные данные
  data do
    # метод params будет возвращать хэш параметров ресурса
    Message.find_by(user_id: client[:user_id]).limit(params[:limit]).map do |msg|
      {
        text: msg.text,
        user: msg.user.name
      }
    end
  end

end

События

.on(event, callback[, context])  // устанавливает обработчик callback на событие event;
.one(event, callback[, context]) // аналогичен методу .on(), но обработчик сработает только один раз;
.off()                           // удаляет все обработчики всех событий;
.off(event)                      // удаляет все обработчики события event;
.off(event, callback)            // удаляет обработчик callback события event;
.off(event, callback, context)   // удаляет обработчик callback события event, 
                                 // установленный с контекстом context;

Api

• ready — генерируется после установки соединения и успешного выполнения обещания beforeReadyPromise;
• unready — генерируется после установки соединения и «провального» выполнения обещания beforeReadyPromise;
• error — генерируется в случае возникновения ошибок в соединении с сервером;
• disconnect — генерируется при отключении от сервера.

Api.connect(address[, options ]) 
// устанавливает соединение с серверной частью
// принимаемые опции:
// aliveDelay - интервал (в миллисекундах) между отправками "ping" пакетов, необязателен, 
// но бывает необходим, если сервер закрывает соединение при неактивности

Api.query( "Messages.new", params ) 
// отправляет запрос в экшен new серверного MessagesController'a
// передает объект params с необходимыми данными

Api.disconnect()
// закрывает соединение с сервером

Api.beforeReadyPromise( callback )
// устанавливает метод, возвращающий обещание (Promise)
// данный метод будет вызван сразу после установки соединения
// и по результатам выполнения обещания сгенерируется событие
// "ready" - в случае успеха или "unready" - при неудаче
// данная возможность бывает полезна, например, для проведения
// авторизации перед запуском приложения

Api.onReady(callback, context)        // аналогичен Api.on("ready", callback, context)
Api.oneReady(callback, context)       // аналогичен Api.one("ready", callback, context)
Api.offReady(callback, context)       // аналогичен Api.off("ready", callback, context)

Api.onUnready(callback, context)      // аналогичен Api.on("unready", callback, context)
Api.oneUnready(callback, context)     // аналогичен Api.one("unready", callback, context)
Api.offUnready(callback, context)     // аналогичен Api.off("unready", callback, context)

Resource

• change — генерируется при обновлении данных ресурса;
• error — генерируется при возникновении ошибки (вызов метода error на сервере).

var resource = new Resource("Messages", {limit: 10})
// откроет серверный MessagesResource с параметрами {limit: 10}

resource.name 
// геттер к названию ресурса

resource.data
// геттер к данным ресурса

resource.get("limit")
// вернет значение параметра limit, в данном случае: 10

resource.set({limit: 20, order: "ask"})
// изменит значение параметра limit и установит новый параметр order
// данные ресурса будут автоматически синхронизированы

resource.unset("order")
// удалит параметр order
// данные ресурса будут автоматически синхронизированы

resource.onChange(callback, context)  // аналогичен resource.on("change", callback, context)
resource.oneChange(callback, context) // аналогичен resource.one("change", callback, context)
resource.offChange(callback, context) // аналогичен resource.off("change", callback, context)

resource.onError(callback, context)   // аналогичен resource.on("error", callback, context)
resource.oneError(callback, context)  // аналогичен resource.one("error", callback, context)
resource.offError(callback, context)  // аналогичен resource.off("error", callback, context)

// ./components/Message.jsx
import React from "react";

class Message extends React.Component {

  render(){
    return (
      <div>
        <b>{ this.props.data.user }</b>
        <p>{ this.props.data.text }</p>
      </div>
    );
  }

}

export default Message;

// ./components/Chat.jsx
import React             from "react";
import Message           from "./Message.jsx";
import { Api, Resource } from "apiway";

// переводим ошибки, вот где нам пригодились
// переопределенные в серверный модели сообщения об ошибках
let errorsMsg = {
  "Text blank":  "Сообщение не может быть пустым",
  "Text length": "Длина сообщения должна быть от 1 до 300 символов"
};

class Chat extends React.Component {

  constructor( props ){
    // определяем начальное состояние компонента
    super( props );
    this.state = { messages: [], errors: [] };
  }

  componentDidMount(){
    // при добавлении компонента на страницу, открываем 
    // ресурс Messages с параметрами { limit: 30 }
    this.MessagesResource = new Resource( "Messages", { limit: 30 } );
    // при изменении ресурса меняем состояние компонента
    this.MessagesResource.onChange(( messages )=>{ this.setState({ messages }) });
    // данный callback будет вызываться каждый раз при обновлении данных
  }

  componentWillUnmount(){
    // уничтожаем ресурс при удалении компонента
    this.MessagesResource.destroy();
  }

  onKeyUp( e ){
    // для отправки сообщений по Enter'у фильтруем нажатие любых клавиш, кроме него
    if( e.keyCode !== 13) return;
    // отправляем запрос в экшен new контроллера Messages, с параметрами {text: "введенный текст"}
    Api.query( "Messages.new", { text: e.target.value } )
    // получаем обещание (Promise)
      .then( ()=>{ this.setState({ errors: [] }) }, ( errors )=>{ this.setState({ errors }) });
    // в случае успеха - обнуляем ошибки, в случае неудачи - устанавливаем новые
  }

  render(){
    return (
      <div>
        // рендерим сообщения
        <div>
          { this.state.messages.map( ( message )=>{ return <Message data={ message } key={ message.id } />; } ) }
        </div>
        // поле ввода
        <input type="text" onKeyUp={ ( e )=> this.onKeyUp( e ) } />
        // переведенные ошибки
        <div>
          { this.state.errors.map( function( key ){ return errorsMsg[ key ]; }).join( ", " ) }
        </div>
      </div>
    );
  }

}

export default Chat;

import React from "react";
import Chat  from "./components/Chat.jsx";

Api
  // подключаемся к серверу
  .connect( `ws://localhost:3000`, { aliveDelay: 5000 } )
  .oneReady( function( e ){
    // и, как только соединение готово к работе, запускаем наше приложение
    React.render( <Chat />, document.getElementById( "app" ) );
  });