ZEN-server

Is the main module of ZEN, that there you will find all necessary tools to create web servers with NodeJS. The main difference from others solutions is the not dependency of third modules, very common in NodeJS projects but that ultimately can create problems.

Our engagement is use the fewer dependencies and offer our experiences with NodeJS easily and intuitive.

• Introduction
  • Installation
  • Configuration
  • HTTPS servers
  • Commands
• API server
  • Our first API endpoint
  • URLs
  • Parameters
  • Session control
  • HTTP Status Messages
• Renderng
  • Our firts WWW endpoint
  • Mustache templates
  • Bindings
  • Blocks
  • Redirections
  • Render files and streaming

## 1. Introduction

ZENserver wants to offer all you need to build applications robust and easy to maintain. Also provides connectors databases with MongoDB and Redis and a connector with APPNIMA.

So, the basic structure of files and folders to work with those features are:

.
├── api
│   └── index.coffee
├── common
│   └── models
├── environment
├── www
│   └── index.coffee
├── package.json
├── zen.js
├── zen.yml

### 1.1 Installation

To install a new instance of ZENserver only you have to run this command:

  npm install zenserver --save

Another option is modify the package.json including this new dependency:

{

  "name"            : "zen-server-instance",
  "version"         : "1.0.0",
  "dependencies": {
    "coffee-script" : "*",
    "zenserver"     : "*" },
  "scripts"         : {"start": "node zen.js"},
  "engines"         : {"node": "*"}
}

We include coffee-script package too, because we go to do all examples in this language. But if you want to develop in JavaScript, you can.

We believe that CoffeeScript is more maintainable and legible, so if you want to learn more of CoffeeScript you can download this free book https://leanpub.com/coffeescript.

### 1.2 Configuration

It is easy to configure ZEN because everything you need is in the configuration file zen.yml. We are goint to analyze these options:

# -- General Info --------------------------------------------------------------
  protocol: http # or https
  host    : localhost
  port    : 8888
  timezone: Europe/Amsterdam

In this section you can set your server configuration, the protocol that you use (http or https), host name, port and timezone.

# -- Environment ---------------------------------------------------------------
  environment: development

With this attribute you can create different configuration files to use in different environments (development, preproduction, production...).

In this example we have established environment so when the server is started searches a file in environment/development.yml route to overwrite the previous configuration on /zen.yml.

# -- RESTful services ----------------------------------------------------------
api:
  - index

# -- HTML pages ----------------------------------------------------------------
www:
  - index

The attributes api and www contain the endpoints of your server. The api is for REST services and the www for others results (HTML, images...).

In this example, ZENserver searches the endpoints /api/index.coffee and /www/index.coffee and will load on the router for further proccesing.

# -- Static resources ----------------------------------------------------------
statics:
  - url     : /temp/resources
    folder  : /static
    maxage  : 60 #secods
  - url     : /img
    folder  : /static/img
  - file    : humans.txt
    folder  : /static
    maxage  : 3600
  - file    : robots.txt
    folder  : /static

This attribute gives us a simple way to provide static files on our server. We can offer complete directories with the url attribute or a specific file by file attribute. In both cases we set the path relative to the project directory using the folder attribute. In case we need to have cache resources we have to set the number of seconds using the attribute maxage.

# -- session -------------------------------------------------------------------
session:
  # Cookie Request
  cookie: zencookie
  domain: ""
  path  : "/"
  expire: 3600 #seconds
  # HTTP Header
  authorization: zenauth

With this attribute we can establish and get easily the session variable for a particular customer. This variable we can get with the attribute cookie.

# -- Monitor -------------------------------------------------------------------
monitor:
  password: mypassword
  process : 10000
  request : 1000

With this attribute we can create an audit to control what happens in our server when it is running. This audit creates a file per day in /logs directory with this information:

• Endpoint requested.
• Which methods: GET, POST, PUT, DELETE,...
• Processing time in milliseconds.
• HTTP code response.
• Response length.
• Client (coming soon).

Learn how to use ZENmonitor.

# -- firewall ------------------------------------------------------------------
firewall:
  ip: 100 #Number of request per firewall rule
  extensions:
    - php
    - sql

You can control packets transiting using firewall option. You just need to set extensions that your application is not configured to handle and ZENserver will return 403 Forbidden. Also, with ip parameter you can set a number of maximum requests that a host can do before get into list blacklist.json.

# -- CORS Properties -----------------------------------------------------------
headers:
  Access-Control-Allow-Origin: "*"
  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
  Access-Control-Max-Age: 1
  Access-Control-Allow-Headers:
    - Accept
    - Accept-Version
    - Content-Length
    - Content-MD5
    - Content-Type
    - Date
    - Api-Version
    - Response-Time
    - Authorization
  Access-Control-Expose-Headers:
    - api-version
    - content-length
    - content-md5
    - content-type
    - date
    - request-id
    - response-time

Finally we set the type of response from our endpoints, to limit access to the same with typical parameters for cross-origin control filtering methods, etc ...

1.3 HTTPS servers

You can create a HTTPS server with ZENserver just setting the protocol attribute and certificates files names:

# -- General Info --------------------------------------------------------------
protocol : https
host     : localhost
port     : 8888
timezone : Europe/Amsterdam

# -- Certificates --------------------------------------------------------------
cert: server.crt
key : server.key

This files must be at *certificates folder at the root of the project. Then you can start your app like always but type in browser: https://127.0.0.1:8888.

### 1.4 Commands To initialize server the command is:

  $node zen.js zen

The content of zen.js must be:

require('zenserver').start();

The server runs in the port that you established in zen.yml file. You can overwrite values of zen.yml with command line:

  $node [JS file] [YML file] [ENVIRONMENT] [PORT]
  $node zen zen production 1980

In this example we established that run zen.js file with these attributes:

• config: Is the configuration file, replacing zen.yml that it is the default file (must be passed without extension yml).
• production: The name of the file of environment for replace the existing environment attribute in the configuration file zen.yml.
• 1980: The new port, replacing the declared in zen.yml

Note that it is not mandatory to set all parameters but respect the order thereof. With this, in case you want to assign a new port number, you must pass the following arguments.

## 2. API server

As you saw, to work with APIs, we need to store the files into /api folder.

### 2.1 Our first API endpoint We go to create a new file called *hello.coffee* in **/api** folder with this code:

  "use strict"
  module.exports = (zen) ->
      zen.get "/hello", (request, response) ->
        response.json hello: "world"

In this case the exported file hello.coffee GET a single endpoint type and whose has path /hello, the callback that runs whenever you access it gives us two parameters:

• request: It is the native object NodeJS but powered with zenserver. In later sections we will see the extras options that zenserver offers on this item.
• response: Like the above is the native object, but as we can see with the (nonexistent in NodeJS) json function comes with extra features.

In this endpoint we are only returning a json object "hello": "world" thanks to .json() method of zenserver.

If we want to capture other methods http we could do it in the same file hello.coffee:

"use strict"

module.exports = (zen) ->

  zen.get "/hello", (request, response) ->
    response.json hello: "world"

  zen.post "/hello", (request, response) ->
    response.json method: "POST"

  zen.put "/api", (request, response) ->
    response.json method: "PUT"

  zen.delete "/api", (request, response) ->
    response.json method: "DELETE"

  zen.head "/api", (request, response) ->
    response.json method: "HEAD"

  zen.options "/api", (request, response) ->
    response.json method: "OPTIONS"

### 2.2 URLs If we need have conditional URLs and that it is managed by the same endpoint, we might to use the conditional router of ZENserver.

For example, we need an endpoint to get when access to an user and a determinated area like this: /user/soyjavi/messages or /user/cataflu/followers, for this we use the conditional URL /user/:id/:context

### 2.3 Parameters With **request.parameters** we have an object with sended parameters. For example, with the URL:

http://domain.com/user/soyjavi/messages?order_by=date&page=20

We have an object like this:

  {
    "id"      : "soyjavi",
    "context" : "messages",
    "order_by": "date",
    "page"    : 20
  }

### 2.4 Session control In case you want to control whether requests that have come to our meeting endpoint can use the request.session which in the case there will return the value of the session object. This may be via cookie or authentication via http. If we want to control if the requests have session, we could use the object **request.session**. This migth be via cookie or HTTP authentication.

In the following example show how to established the cookie and how to do logout:

  zen.get "/login", (request, response) ->
    response.session "10293sjad092a"
    response.json "cookie": true

  zen.get "/logout", (request, response) ->
    response.logout()
    response.json "cookie": false

## 2.5 HTTP Status Messages For now we only know the json method superficially, besides setting the object that we want to return, we can indicate a HttpStatusCode (default 200) and a HTTPHeaders. For example:

  values =
      username: "cataflu",
      name    : "Catalina"
  headers =
    domain    : "http://domain.com"
  response.json values, 201, headers

As you can see it's really simple, but to further facilitate the zenserver things HTTPStatus offers predefined. For example if a given endpoint want to return the client does not have permission just have to call response.badRequest () method and will handle zenserver create a 401 response with the message "Bad Request".

ZENserver offers HTTPStatus predefined:

response.badRequest()

Then list all HTTPStatus: 2xx Successful

200: "ok"
201: "created"
202: "accepted"
204: "noContent"

4xx Client Error

400: "badRequest"
401: "unauthorized"
402: "paymentRequired"
403: "forbidden"
404: "notFound"
405: "methodNotAllowed"
406: "notAcceptable"
407: "proxyAuthenticationRequired"
408: "requestTimeout"
409: "conflict"

5xx Server Error

500: "internalServerError"
501: "notImplemented"
502: "badGateway"
503: "serviceUnavailable"
504: "gatewayTimeout"
505: "HTTPVersionNotSupported"

## 3. Rendering ### 3.1 Our firts WWW endpoint We are goint to create *form.coffee* file in **/www** directory and with this code:

zen.get "/form", (request, response) ->
  response.html """
    <form action="/form" method="post">
      <input type="text" name="name">
      <input type="text" name="username">
      <input type="file" name="media">
      <input type="submit" value="Submit">
    </form>
  """

We use .html() method to render all HTML code; it is similar to .json().

### 3.2 Mustache template You've learned how to return HTML code in a particular endpoint, but really, this is not efficient option. Now you will learn to use the Mustache templates that are included in zenserver to facilitate reuse and management of your pages correctly.

We are goint to create a file base.mustache in /www/mustache directory with this code:

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>ZENServer</title>
</head>
<body>
    <header>
        <h1>Hello World!</h1>
        More info & code
        <a href="https://github.com/soyjavi/zen-server" target="_blank">GitHUB</a>
    </header>

</body>
</html>

Now we create a new endpoint (index.coffee) that render create template when access to /:

zen.get "/", (request, response) ->
  response.page "base"

With the method .page() we indicate to ZENserver that search a file with name "base" in /www/mustache directory.

If this file not exists, ZENserver search a 404.mustache file to render. And if you dont create it, ZENserver return a <h1> 404 - Not found</h1> HTML.

### 3.3 Bindings In the previous chapter we have seen a simple page rendering by a Mustache file. Anyway we have not used any of the features Mustache offers.

We will send details to our staff so that renderize, this is known as data binding. To do this we will modify our base.mustache template:

...
  <h1>Hello World! {{title}}</h1>
...

Now, we send through our enpoints the bingin title:

zen.get "/", (request, response) ->
  bindings =
    title   : "ZENserver"
    session: request.session

  response.page "base", bindings

### 3.4 Blocks Imagine that we will use a section of HTML in multiple pages, it would be better to insulate this HTML code and to include it in all the templates you need, right?. Well let's see what we can do with our mustache template:

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
</head>
<body>
    <header>
        <h1>{{title}}</h1>
        More info & code
        <a href="https://github.com/soyjavi/zen-server" target="_blank">GitHUB</a>
    </header>

    {{> partial.example}}
    {{> partial.session}}
</body>
</html>

We have created two references to mustache block {{> partial.example}} and {{> partial.session}}. We are goint to create in the same level of the rest of mustaches with partial.example.mustache name:

partial.example.mustache

<section>
    <h2>partial.example</h2>
    subdomain: <strong>{{user.name}}</strong>
    mobile: <strong>{{mobile}}</strong>
</section>

partial.session.mustache

<section>
    <h2>partial.session</h2>
    Session: <strong>{{session}}</strong>
    <nav>
        <a href="/session/login">Login</a>
        <a href="/session/logout">Logout</a>
    </nav>
</section>

Now, from our endpoint we completed the new binding:

  zen.get "/", (request, response, next) ->
    bindings =
      title : "zenserver"
      user  :
        name: "@soyjavi"
      session: request.session
      mobile : request.mobile
    partials = ["partial.example", "partial.session"]

    response.page "base", bindings, partials

### 3.5 Redirections If we need to do redirection to an another endpoint, we use the following method **.redirect()**:

zen.get "/dashboard", (request, response) ->
  if response.session
    response.page "dashboard", bindings, partials
  else
    response.redirect "/login"

### 3.6 Render files and streaming

Although NodeJS is not the best way to serve static files zenserver provides a simple and efficient solution for this purpose.

Only we shall have to use the response.file method which will analyze the file type you want to serve and provide the best method of transmission. For example if we are trying to serve some sort of multimedia files such as video or audio, zenserver automatically performs a streaming it. Here's an example:

  zen.get "/vídeo/:id", (request, response) ->
    response.file "/assets/vídeo/#{request.parameters.id}.avi"

As you can see it is very simple, since all zenserver responsibility to decide how to transmit the file is delegated. Noted that in the event that the file did not exist zenserver /assets/vídeo/?.id return a HttpStatusCode 404.

The response.file method will make a small caching on the client, by default 60 seconds, in case you want to increase or decrease the caching, we just have to pass in the second parameter:

  url_file = "/assets/image/tapquo.jpg"
  response.file url_file, maxage = 3600

In this case, we have assigned the file /assets/image/tapquo.jpg a cache on the client 1 hour (3600 seconds).