zenserver

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 dependence 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.

1. Introduction

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 dependence:

{

  "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:

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: 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 environments/development.yml route to overwrite the previous configuration on /zen.yml.

api:

	- index

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.

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. 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:

  # 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.

audit:

  interval: 60000 #miliseconds

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:

- Requested endpoint

- Method (GET, POST, PUT, DELETE)
- Processing time in milliseconds
- Response HTPP code
- Response size in bytes
- Client (comming soon)

With this information you can analize all requests of your clients.

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

1.4 Commands

To initialize server the command is:

	$node zen.js zen

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 config 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

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.

En el caso de que quisiesemos capturar otros métodos http podríamos hacerlo en el mismo fichero hello.coffee. Veamos como podríamos capturar otros métodos además del GET:

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. Servidor Páginas

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

404 - Not found

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:

	<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:

	<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:

	  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).