Yoi

Yoi is a server based on the NodeJS technology, is very simple but able to supply many of the most common needs of web server and many other general purpose tools. Yoi is written in CoffeeScript for better readability and maintainability.

To use Yoi is necessary to install NodeJS and NPM package manager.

In yoi-instance we find an example of the basic structure of a server with Yoi.

package.json

This file contains the basic project data and all necessary dependencies that we need to start:

{
  "name"            : "yoi-instance",
  "version"         : "1.04.22",
  "description"     : "Easy (but powerful) example of YOI Instance",
  "homepage"        : "http://",
  "author"          : "Javi Jimenez <javi@tapquo.com>",
  "dependencies": {
    "coffee-script" : "*",
    "yoi"           : "*" },
  "devDependencies" : {},
  "scripts"         : {
    "start": "node yoi.js yoi development" ,
    "test": "node yoitest.js" },
  "engines"         : { "node": "*"}
}

yoi.yml

In this file is defined the basic configuration of our Yoi, for example the desired environment, where to find our "endpoints" or our "assets", the frequencies of the crons…

environment: development

endpoints:
    api:
        - example
    www:
        - example
 
assets:
  - folder : js
    maxage: 3600
  - folder: css
    maxage: 3600
  - folder: img
 
crons:
  - name    : Example of 5 seconds job
    schedule: "*/5 * * * * *"
    file    : example
    timezone: Europe/Madrid

yoi.js

This is an essential file because is responsible for starting the server.

"use strict";

require("coffee-script");
require("yoi").run();

environments

As we can see, the first property of the yoi.yml is the working environment. Yoi allows us have different environments to start up the server in different contexts. In the folder "environments", found within the "yoi" folder, create a file by environment , whose name correspond with the attribute "environment" of yoi.yml. Here you can define things like "host", port, the database…

server:
  type: development
  host: localhost
  port: 1337
  
mongo:
  - name    : primary
    host    : localhost
    port    : 27017
    db      : db_name
    user    : db_user
    password: db_password
…

Once configured the above, simply run the command in terminal "npm install", which will install all dependencies of the package.json and as seen in this file, with "npm start" command start up the server.

Api

A project of Yoi, as seen in the instance, in yoi/api contains the file that defining the REST APIs. These files have the extension .coffee and should be referenced in the yoi.yml.

endpoints:
  api:
    - example

An API is defined this way:

server.get "/api/contact", (request, response, next) ->
  rest = new Yoi.Rest request, response
  rest.required ["name"]
  name = rest.parameter "name"
  rest.run
    "status": "Hello #{name}!"

This API is executed with a REST request of type "GET" to "http://localhost:1337/api/contact".

Also is possible to make requests type "POST":

server.post "/api/contact", (request, response, next) ->
  rest = new Yoi.Rest request, response
  rest.run
    "action": "Petición POST"

type "PUT":

server.put "/api/contact", (request, response, next) ->
  rest = new Yoi.Rest request, response
  rest.run
    "action": "Petición PUT"

and type "DELETE":

server.del "/api/contact", (request, response, next) ->
  rest = new Yoi.Rest request, response
  rest.run
    "action": "Petición DELETE"

Web requests

Also in yoi/www we found the files that catch web requests. Along with these files is another folder that contains the "templates". These files and the "templates", must be referenced in the yoi.yml.

endpoints:
  www:
    - example
   
templates: endpoints/www/templates

Web requests are collected as follows:

server.get "/", (request, response, next) ->
  site = new Yoi.Site request, response
  bindings =
    session: site.session
  site.template "index", bindings

This means That When making a call to "http://localhost:1337/" on screen to load the "template" named "index".

Through the bindings object is allowed to access the data of the object within the "template".

Assets

To load "assets" such as CSS styles, "scripts" or images on our website, are included in the yoi/assets directory in the appropriate folder, and indicate where to find those folders into the yoi.yml.

assets:
  - folder : js
    maxage: 3600
  - folder: css
    maxage: 3600
  - folder: img
    maxage: 3600

Followed add in our "template" the tag to load the corresponding files.

Tests

Yoi provides an environment to test our APIS. The required files are: yoitest.js and yoitest.yml.

yoitest.js has the necesary to start the test:

"use strict";

require("coffee-script");
require("yoi").test();

The yoitest.yml file has an attribute "files" wich indicates what test files are going to be laoded. These files must be in the "test" folder and files are .coffee.

files:
  - example_test

We can create a Mock for help us to test our APIS. This is an example of how defined two users in yoitest.yml:

users:
  - name      : Pedro
    mail      : pedro@doe.com
  - name      : Carmen
    mail      : carmen@sandiego.com

To run the tests, it is recommended to follow this structure.

"use strict"

Yoi = require "yoi"

module.exports = -> 

  tasks = []
  tasks.push _apiWithName(user) for user in test.users
  tasks

_apiWithName = (user) -> ->
  Yoi.Test "GET", "api", user, null, "Call api with #{user.name} for parameter 'name'", 200      

The parameters that are sent to be tested are: the type of request ( "GET", "POST", "PUT", "DELETE", "OPTIONS"), the url of api without domain, the parameters that are sent to that API, the headers we want to send, and the expected response caught.

Finally to launch these tests only need to run the console:

node yoitest.js

In terminal will be listed one by one if the test has been successful or not.

Crons

In Yoi the crons are routines in background that run at regular intervals. These routines are planned and remain temporarily on hold until the time of execution.

To define the cron in our yoi.yml must include your name, how often, the name of the file where the cron is implemented within "yoi/crons" and the time zone of the server time.

crons:
  - name    : Example of 5 seconds job
    schedule: "*/5 * * * * *"
    file    : example_cron
    timezone: Europe/Madrid

To implement the cron you must first create a class that extends Yoi.cron and implement the method below.

"use strict"

Yoi = require "yoi"

class ExampleCron extends Yoi.Cron

  count = 0

  execute: ->
    count++

exports = module.exports = ExampleCron

The method "execute" will be run in each interval.

You can also add a method to be executed after each interval. The method is defined as follows:

stop: ->
  super
  console.log "count: #{count}"

Crawlers

Yoi also allows us to implement crawlers, which are routines to scan web pages a of way a methodical, automated in order to access the content of these pages.

The way to add a crawler to Yoi is the same as a cron. Inside the folder yoi/crons create a file and add in our crawler yoi.yml the cron.

crons:
  - name    : Crawler Sample
    schedule: "*/5 * * * * *"
    file    : example_crawler
    timezone: Europe/Amsterdam

This time the class must extend from Yoi.Crawler

"use strict"

Yoi = require "yoi"
$   = Yoi.$

class CrawlerSample extends Yoi.Crawler


exports = module.exports = CrawlerSample

The first function to execute is "start" method within that class:

start: =>
  urls = []
  for category in C.CATEGORIES
     urls.push "#{C.DOMAIN}#{category}"
  super urls, @item

This is the main function. It will add an array all urls where you want to run the crawler and super charge these urls and will pass the function you want to run with each load.

item: (error, response, body) ->
  body.find(".entry-content > p").each (index, link) =>
    @results.push p.data for p in link.children when p.type is 'text'

As seen, the function receives the body of the page, and you just have to manipulate the elements to get the desired information.

If you want to access more pages in our code, the function is:

@queue "#{next_page}", @page 

The parameters that are sent are the url of the page and the method you want to call to receive it.

There is a method that is executed at the end of the function of the crawler.

finish: ->
  super
    console.log "Fin"

Yoi.Hope

Hope is a system of promises for chaining callbacks. We have 4 types:

Join

Executes functions in parallel and ends when they have finished all functions. Returns an array of results and other of errors.

Yoi.Hope.join([ =>
  first()
, =>
  second()
]).then (errors, values) ->
  console.log(errors, results)

Chain

Chain executes all functions sequentially, allowing pass the result of one function to another. Returns the last error and result.

Yoi.Hope.chain([
  ->
    late(100)
  (error, result) ->
    late(result + 200)
]).then (error, result) ->
  console.log result    

Shield

Shield works similar to Chain, the difference is that if one of the functions returns an error when running the following are not executed. Returns the last error and result.

Yoi.Hope.shield([
   ->
    method 1
  , ->
    method 10
  , ->
    method 2
]).then (error, result) ->
  if error? then console.log error

Yoi.Appnima

Appnima provides a number of common features to all projects. Through Yoi we can access all of them quickly.

Here an example of how a user registers using this service.

Yoi.Appnima.signup request.headers["user-agent"], rest.parameter("mail"), rest.parameter("password"), rest.parameter("username"),( error, user) ->
	console.log	 user

Also provides of quick access for doing "Login":

Yoi.Appnima.login user_agent, mail, password , username, (error, user) ->
	console.log	 user

and a "refreshToken" which updates the user's security token:

Yoi.Appnima.refreshToken user_agent, refresh_token, (error, new_token) ->
	console.log new_token

Finally, Yoi.Appima.api gives us access to all other features of Appnima. To know all APIs you can access: documentation Appnima. An example of use would be:

Yoi.Appnima.api request.headers["user-agent"], "POST", "user/reset/password", null, parameters, (error, result) =>
   if error then rest.notFound() else rest.successful()

Yoi.Mongo

To access a Mongo data base through Yoi , the first step is to define the database in the yoi.yml.

mongo:
 - name    : primary
   host    : localhost
   port    : 27017
   db      : db_name
   user    : db_user
   password: db_password

To interact with it you just have to get an instance of the database with Yoi.Mongo service. An example:

db = Yoi.Mongo.connections.primary

And with this you can interact with the database.

db.users.find(query)

Yoi.Redis

Yoi offers a system of "redistribution", to use the first thing to do is to define the parameters in the ".yml" environment desired.

redis:
    host : HOST
    port : port

An example of how it is used:

Yoi.Redis.get key, (error, result) -> console.log result

Yoi.Mongoose

Yoi also provides a ODM for Mongo data bases called Mongoose.

The instance is created in the following way:

Schema    = Yoi.Mongoose.Schema

To define the model:

User = new Schema
  mail      : type: String
  name      : type: String

And an example of the definition of its methods:

User.statics.findByMail = (mail) ->
  promise = new Yoi.Hope.Promise()
  @findOne(mail: mail).exec (error, value) ->
    if not value
      error = code: 401, message: "User not found"
      promise.done error, null
    promise.done error, value
  promise

Deploy

Thanks to this feature you can set a series of actions or tasks that run on our server automatically.

The tasks which get executed on the server must be defined in the .yml our environment in the following way:

deploy:
  - ls -l
  - ls -lia

To run the task, just run the following method from any API:

Yoi.Deploy.tasks().then (error, pid) ->
   console.log "Executing tasks!"

With Yoi.Deploy you can configure your server to be linked to a code repository.

With this module you can configure a series of actions or tasks you want to run on our server automatically for an environment with integration continues. This is explained in the manual Yoi.