Objeto Gangway Pillars.js Reference

Source

Sumario

Pillars.js genera de forma automática un objeto gangway en cada petición. Tiene como propiedades los datos del request parseados y métodos para la respuesta.

Pasea los datos del request y los setea en sus propiedades para que sean más accesibles y usables directamente. Además sus métodos están vitaminados, por ejemplo gw.file(), que envía archivos, tiene implementado byte-serving, esto quiere decir que permite descargas por partes y streaming :)

Este objeto está disponible en el handler tanto del objeto route, como en el objeto middleware.

var myRoute = new Route(function(gw){

var POST = gw.content.params;

var GET = gw.query;

var cookie = gw.cookie;

var userAgent = gw.ua;
/*
ua:{
mobile: false,
os: 'Windows NT 6.1; WOW64',
engine: 'Blink',
browser: 'Chrome'
}
*/



var id = gw.id; // id del objeto gangway para la petición.
var ip = gw.ip; // ip del cliente
var browserLang = gw.language; // Primer idioma del navegador del cliente
var cors = gw.cors; // Gestion de orígenes cruzados.
var method = gw.method; // Método de la petición GET y/o POST
var encoding = gw.encoding; // encoding que se utiliza para el envío al cliente.

gw.json(gw);
});

Propiedades

gw.events

Propiedad de tipo ObjectArray. Contiene eventos.

gw.responseTime

Tiempo que se tarda en resolver la respuesta, justo antes de comenzar el envío de la misma.

gw.timer

TimeStamp del instante en el que se creó el objeto gangway.

gw.id

String. Id del objeto gangway, se genera automáticamente.

gw.req

Alias del objeto request original de Node.

gw.res

Alias del objeto response original de Node.

gw.socket

Socket de la solicitud. Es un alias de request.socket de Node.

gw.statusCode

Código de estado de la solicitud. Alias de response.statusCode original de Node.

gw.headersSent

Informa si se han enviado las cabeceras de la respuesta o no. Alias de response.headersSent original de Node.

gw.headers

Alias de request.headers original de Node.js.

gw.finished

Alias de response.finished original de Node.js.

gw.accepts

Engloba los encabezados del protocolo HTTP Accept, Accept-Language y Accept-Encoding. Estos valores siguen en su forma original el RFC de Quality Values. Pillars.js ordena y establece de una forma homogénea estos parámetros en las siguientes propiedades:

.accepts devuelve un objeto con:

  • .accepts.types: Array que contiene los Content-types que espera como respuesta el navegador en la solicitud. RFC Accept.
  • .accepts.languages: Array que contiene los idiomas que espera el navegador. El idioma que utilizará el servidor en el envío se setea en gw.language.RFC Accept-Language.
  • .accepts.encodings: Array que contiene los encodings que soporta el navegador. El encoding que utilizará el servidor se setea en gw.encoding. RFC Accept-Encoding.

    Ejemplos

gw.content

En esta propiedad se engloban los encabezados y valores relacionados con el cuerpo de la solicitud.

  • .type: Encabezado Content-Type de la solicitud.
  • .length: Encabezado Content-length de la solicitud, indica el tamaño en bytes del cuerpo.
  • .boundary: Aparece solo en las solicitudes POST del tipo multipart/form-data. Es extraido de Content-type.
  • .params: Es la ubicación donde el middleware BodyReader guardará los parámetros recibidos en el cuerpo de la solicitud. Estos son copiados también en la propiedad gw.params, donde se combinan con los recibidos mediante GET.

gw.ranges

Relacionado con la solicitudes byte-serving, esto es, cuando se solicita una porción de un contenido previamente descargado de forma parcial. Por ejemplo; una imagen cuya descarga ha sido interrumpida, o un video que se está ejecutando con un reproductor multimedia. Para una solicitud sin rangos la propiedad .ranges es false, en caso contrario .ranges será un objeto con las siguientes propiedades:

  • .check: indica el eTag del contenido del cual se solicita el rango. Algunos navegadores y reproductores de video, por ejemplo, no añaden este dato, siendo en estos casos false.
  • .unit: unidad en la que se solicitan los rangos. Normalmente bytes.
  • .start: byte de comienzo.
  • .end: byte de finalización.

El objeto gangway maneja ranges de forma automática cuando se van a enviar ficheros mediante gw.file().

Objeto que contiene los valores recibidos mediante cookies.

gw.auth

Contiene los valores recibidos en la cabecera HTTP Authorization.RFC. Devuelve false, en caso de no haberse recibido dicha cabecera y un objeto con las propiedades .user y .pass en el caso de haberse recibido. Para solicitar al cliente dicha validación esta disponible el método .authenticate().

auth:{
user: 'UserName',
pass: 'PassUser'
}

gw.ua

Contiene información relativa al cliente extraido del encabezado HTTP User-Agent (RFC):

  • .mobile: Boolean. Si es dispositivo móvil o no.
  • .os: String con el Sistema Operativo del cliente.
  • .engine: String. Motor de renderizado. Gecko, Webkit, Trident, Blink o Unknow.
  • .browser: String. Navegador del cliente. Firefox, Seamonkey, Chrome, Chromium, Safari, Opera, MSIE o Unknow.
ua:{ 
mobile: false,
os: 'Windows NT 6.1; WOW64',
engine: 'Blink',
browser: 'Chrome'
}

gw.origin

Encabezado Origin relacionado con las solicitudes CORS.

gw.ip

Dirección IP del cliente. String.

console.log(gw.ip);
//>127.0.0.1

gw.httpVersion

Versión del protocolo HTTP.

gw.https

Indica si la solicitud ha sido realizada a un servicio https o no. Boolean.

gw.host

Host al que se realiza la petición. String

console.log(gw.host);
//>localhost

gw.port

Puerto al que se realiza la petición.

console.log(gw.port);
//>3000

gw.method

Método utilizado para la petición. Uno de los siguientes valores [OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT]

console.log(gw.method);
//>GET

gw.path

Path completo al que se realiza la petición. Puede sufrir modificaciones, por ejemplo por el sistema de traducciones o cualquier otra redirección interna, en cualquier caso estará disponible una copia del path original en la propiedad .originalPath.

//http://sub.dom.ext/a/b/c?a=A&b=B
"/a/b/c"

gw.originalPath

Path original desde el que se realiza la petición. Ver gw.path.

console.log(gw.originalPath);
//>/

gw.query

Parámetros recibidos en el query string de la solicitud.

// Se visita http://sub.dom.ext/a/b/c?a=A&b=B
//> gw.query: {a:'A',b:'B'}
gw.send("Has enviado mediante Query String el valor: " + gw.query['a']);

gw.referer

Contiene el valor del encabezado HTTP Referer que indica, si es el caso, la URL del sitio web que contenía el enlace que lanzó esta solicitud.

gw.connection

Contiene el valor del encabezado HTTP Connection.

console.log(gw.connection);
//>keep-alive

gw.cache

Esta propiedad engloba los valores relacionados con la negociación de caché con el cliente. Contiene las siguientes propiedades:

  • .control: contiene el valor del encabezado HTTP cache-control.
  • .eTag: contiene el valor del encabezado HTTP if-none-match. Este encabezado está relacionado con el encabezado de la respuesta eTag que es encriptado para el cliente y se obtiene en esta propiedad ya desencriptado.
  • .lastMod: contiene el valor del encabezado HTTP if-modified-since.
console.log(gw.cache);
//>{
// control: 'max-age=0',
// eTag: false, // va con el eTag
// lastMod: 'Tue, 30 Dec 2014 18:47:00 GMT'
// },

gw.files

Contiene los ficheros contenidos en el cuerpo de la solicitud en el caso de ser multipart/form-data. Pillars.js por defecto utiliza a la librería formidable para recibir los ficheros, por lo que en esta propiedad se encuentran las referencias a los archivos en el formato que ofrece esta librería.

gw.pathParams

Contiene un objeto con los parámetros y valores que han llegado al servidor a través de la Ruta parametrizada. En Pillars.js puedes configurar los path de los objetos Route con parámetros abiertos. /:var, /*:var, /:var1/:var.

var route = new Route({path:'/:var1/:var2'},function(gw){
gw.json(gw.pathParams);
});
//Consultando localhost:300/users/john imprime:
//>{var1: 'users', var2:'john'}

gw.params

Contiene los parámetros recibidos tanto por query string como en el cuerpo de la solicitud y mediante parametros de ruta. Es decir, gw.pathParams (/:var, /*:var) + gw.query (?q=1) + gw.content.params(POST).

gw.data

Objeto disponible para añadir propiedades y valores adicionales.

gw.encoding

Encoding que va a usar el servidor para la respuesta. Está basado en gw.accepts.encodings. Pillars.js es compatible con las codificaciones identity, deflate y gzip.

gw.language

Idioma que va a usar el servidor para la respuesta. Está basado en la URL utilizada para la solicitud, esta propiedad es establecida por el Middleware LangPath.

gw.responseCookies

Es un Array que contiene las cookies que han sido establecidas por el método de gangway .setCookie(). Al enviar la respuesta al cliente se adjuntarán las cookies establecidas en este Array.

gw.cors

Cabeceras relacionas con solicitudes CORS para la respuesta al cliente. Estas propiedades son definidas por el Middleware CORS automáticamente.

//cors: {
// origin: false,
// credentials: false,
// methods: false,
// headers: false }

gw.size

Tamaño en bytes de la respuesta al cliente. Es usado para generar el encabezado HTTP Content-Length cuando ejecutamos cualquier método de envío a cliente. De forma general se rellena automática con cualquiera de los métodos de respueta de gangway.

gw.lastMod

La propiedad .lastMod (objeto Date) indica la fecha de última modificación de la respuesta, este valor es usado para generar el encabezado HTTP Last-modified. Por defecto será la fecha y hora en la que se efectúa dicha respuesta de no ser establecida esta propiedad antes de comenzar la respuesta al cliente.

gw.eTag

Esta propiedad sirve para establecer el encabezado HTTP eTag de la respuesta. Consiste en un objeto que será encriptado mediante JSON.encrypt() para ser enviado al cliente. Por lo que podemos definir múltiples valores detro de la cabecera eTag. Pillars.js utiliza la propiedad gw.eTag.hash para establecer el identificador único o hash del contenido enviado. Este hash único se establece con el método .cacheck() ya que es el valor utilizado para controlar la versión en caché del cliente del contenido solicitado.

gw.maxAge

Establece los encabezados HTTP Expires y Cache-control:max-age. Debe contener el número de segundos que debe mantenerse dicho contenido en la caché del cliente.

gw.routing

Propiedad no nativa del objeto gangway. Es añadida por el Middleware router.js. Contiene un referencia a todos los objetos route por los que va pasando Pillars.js hasta llegar al que atenderá la petición. En gw.routing encontramos:

  • inheritance: parámetros de configuración declarados en el objeto route que atiende la petición y sus antecesores en el caso de ser una estructura arbórea. Finalmente queda un listado de propiedades heredadas.

    Ver herencia de parámetros de configuración de un objeto route en una estructura arbórea.

  • routes: dada una estructura arbórea, array que contiene todos los objetos route que se recorren en el árbol hasta llegar al que atiende finalmente la petición.
  • handlers: handler o handlers que atienden finalmente la petición.

Métodos:

  • .check(): chequeo rápido de las propiedades heredadas. Dados unos parámetros heredados, chequeo de las mismas:
var userParam = gw.routing.check("userParam", project.config.userParam || '56');

Si no viene heredada la propiedad userParam, establece su valor con pillars.config.userParam, en el caso de que sea undefined lo establece en 56.

gw.session

Propiedad no nativa del objeto gangway. Es añadida por el Middleware sessions.js. Contiene los datos de la sesión.

Métodos

gw.setTimeout()

Alias de response.setTimeout(msecs, callback) de Node.

gw.writeContinue()

Alias de response.writeContinue(statusCode, [reasonPhrase], [headers]) de Node.

gw.writeHead()

Alias de response.writeHead(statusCode, [reasonPhrase], [headers]) de Node.

gw.setHeader()

Alias de response.setHeader(name, value) de Node.

gw.getHeader()

Alias de response.getHeader(name) de Node.

gw.removeHeader()

Alias de response.removeHeader(name) de Node.

gw.addTrailers()

Alias de response.addTrailers(headers) de Node.

gw.write()

Alias de response.write(chunk, [encoding]) de Node.

gw.end()

Alias de response.end([data], [encoding]) de Node.

gw.setCookie()

Guarda una nueva cookie para el envío en la respuesta.

Sintaxis

.setCookie(name, value, config);
  • name: String nombre de la cookie.
  • value: String valor de la cookie.
  • config: objeto de configuración de la cookie que puede contener los siguientes parámetros:
    • domain: nombre de host sobre el que va a funcionar la cookie.
    • path: define el alcance de la cookie.
    • expires: tiempo de duración de la cookie.
    • maxAge: máximo número de segundos que deberá conservarse la cookie.
    • secure: cookie en modo seguro.
    • httpOnly: Establece la propiedad httpOnly de la cookie.

gw.i18n()

El método .i18n de gangway es un alias de la librería textualization con el valor del idioma preestablecido al idioma actual del gangway, es decir, se puede utilizar gw.i18n sin necesidad de especificar el idioma en la sentencia.

Sintaxis

.i18n(nodo, params [, lang]); 
  • nodo: String, nodo a traducir.
  • params: objeto con propiedades a pasar como parámetros para la traducción.
  • lang: idioma a utilizar si no fuese el propio de este objeto gangway.

gw.file()

Envía al cliente un archivo y finaliza la petición. Gestiona el sistema de caché e implementa byte-serving, esto quiere decir que realiza la negociación automática de rango de bytes en la descarga, por lo que permite descargas por partes y streaming.

Si el archivo a enviar es menor o igual al tamaño declarado en project.config.maxCacheFileSize se realiza compresión del archivo y cambia el encoding a deflate o gzip, cacheando este contenido para sucesivas solicitudes.

Sintaxis

.file(filename [, clientname , download]);
  • filename: String, fichero a enviar, dentro del sistema de archivos del servidor.
  • clientname: Opcional, String con el nombre del fichero para el cliente, en caso de que no sea el mismo que el original.
  • download: Opcional, Boolean. True para forzar el diálogo de descarga. Por defecto es false.

Nota: Este método también tiene gestión de caché automática, por lo que si el cliente ya tiene el archivo no volverá a ser enviado y se responderá con un código 304.

Ejemplo

gw.file("document.pdf");

gw.cacheck()

Permite gestionar la caché con el cliente, debemos pasar un valor único identificativo (hash) del contenido de la respuesta. Este método responderá con false si el cliente no tiene cacheado el contenido y true junto con un 304 automáticamente si el cliente ya dispone del contenido. La forma ideal de utilizar este método es como condición en una sentencia if, de la forma if(!cacheck(hash)){}, como vemos en el ejemplo.

Sintaxis

.cacheck( hash );
  • hash: Mixed con valor único identificativo.

Ejemplo

var hash = new Date("2015-01-01");

if (!gw.cacheck(hash)){
gw.json({ok:true});
}

El valor pasado a cacheck puede ser un código de tiempo o un objeto Date, que nos servirá para identificar el contenido. En este ejemplo se devolverá en una primera solicitud un código 200 con el objeto JSON, y en sucesivas solicitudes se responderá en cualquier caso con un 304.

gw.authenticate()

Emite un código de estado 401 con el encabezado WWW-Authenticate es una cabecera HTTP que emite un diálogo en cliente solicitando usuario y contraseña.

El conjunto .authenticate() y .auth son similares a la restricción de acceso que se realiza en el archivo .htaccess en otros servidores HTTP.

Sintaxis

.authenticate(msg);
  • msg: String. Mensaje a mostrar al usuario.

Ejemplo

var route = new Route(function(gw){

if(gw.auth && gw.auth.user=='javi' && gw.auth.pass=='1234'){
gw.send('secret!');
} else {
gw.authenticate("Escribe tu nombre y contraseña");
}

});

gw.redirect()

Redirección a la URL indicada.

Sintaxis

.redirect(urlToRedirect);
  • urlToRedirect: String. URL de la redirección.

Ejemplo

gw.redirect("www.pillarsjs.com");

gw.send()

Método para enviar una respuesta al cliente. Si la respuesta es un string se envía como text/html y si es un objeto lo envía como objeto parseado tipo application/json. Cuando se llama al método .send() finaliza la ejecución del route en cuestión.

Este método tiene alias más específicos para cada tipo de contenido a enviar como son: gw.json() gw.text() y gw.html() que se detallan más adelante.

Sintaxis

.send(data,type);
  • data: String o Object con el contenido a enviar.
  • type: Opcional. "text/html", "application/json", "text/plain" ... para forzar un tipo concreto en el envío.

Ejemplo

gw.send("Hola Mundo!");

gw.json()

Envía al cliente una respuesta en formato application/json.

Sintaxis

.json(data);
  • data: Object a enviar como JSON.

Ejemplo

var dataPerson = {
"id":"246874113",
"name": "myname",
"surname": "mysurname"
}

gw.json(DataPerson);

gw.text()

Envía al cliente la respuesta parseada como 'text/plain'.

Sintaxis

.text(data);
  • data: String con el texto a enviar.

Ejemplo

gw.text("Hola Mundo!!");

gw.html()

Envía al cliente la respuesta parseada como 'text/html'.

Sintaxis

.html(data);
  • data: String con el contenido html a enviar.

Ejemplo

gw.html("<h1>Title</h1>");

gw.render()

Este método permite enviar al cliente un template renderizado. Hace uso de la librería Templated.

Templated da soporte a prácticamente cualquier motor de renderizado, por lo que podrás utilizar el lenguage de plantillas HTML de tu preferencia. En el siguiente código se muestra cómo añadir soporte a jade en nuestro proyecto:

var templated = require('templated');
var jade = require('jade');

templated.addEngine('jade',function(source,path){
return jade.compile(source,{
filename:path,
pretty:true,
debug:false,
compileDebug:true
});
});

Para renderizar una plantilla es necesario especificar la ubicación de la misma y un objeto con los parámetros a utilizar en dicha plantilla conocido como 'locals'. El metodo .render() añade de forma automática a 'locals' las propiedades:

  • gw: Referencia al Gangaway actual.
  • i18n: Referencia al metodo gw.i18n()
  • pillars: Referencia al proyecto o entorno.

Sintaxis

.render( template [, locals] ) 
  • template: String, ruta del template.
  • locals: Object, conjunto de parámetros para el renderizado de la plantilla.

Ejemplo

gw.render("example.jade", {title:"Título de página", h1:"h1 de la página"} );
// example.jade
title=title
h1=h1
El idioma es #{gw.language}


gw.error()

Compone una página genérica de error HTTP con el código de estado especificado, opcionalmente se le puede pasar el objeto Error de JS para su trazado.

Pillars.js utiliza un template por defecto para componer la página de error. Se puede modificar este template mediante la propiedad project.config.errorTemplate.

Sintaxis

.error(errorCode [, error]) 

Ejemplo

gw.error(500);

POST, GET y rutas parametrizadas

  • Query String (GET). Se conoce como Query String a la parte de la URL que contiene los datos que se deben pasar a aplicaciones. Comúnmente, en PHP, lo que se conocía como el GET. Por lo tanto, si se recibe una petición con datos en el query string, se encontrará seteado en gw.query.
// Se visita http://sub.dom.ext/a/b/c?a=A&b=B
//> gw.query: {a:'A',b:'B'}
gw.send("Has enviado mediante Query String 'a' co el valor: " + gw.query['a'] +
" y 'b' con el valor: " + gw.query['b'] );
  • Contenido de la petición (POST). El contenido obtenido por POST se setea en la propiedad gw.content.params de una forma accesible. En el caso de subida de ficheros, hemos de tener en cuenta que el objeto route debe estar configurado para aceptar multipart/form-data. En el caso de no estar definido method, aceptará todos.
var myRoute = new Route(
{
path: '/uploads',
multipart: true
},
function(gw){
//...
});

Los ficheros de la petición serán seteados en gw.files y almacenados en el directorio /temp. Si deseamos cambiar este directorio temporal, podemos hacerlo mediante la propiedad .tempDirectory del plugin bodyReader.js.

No olvides cambiar los archivos de ubicación, ya que en /temp sólo se almacenan temporalmente hasta que el manejador del controlador finaliza.
  • Rutas parametrizadas. El uso de rutas parametrizadas tiene que estar declarado en el objeto route. Una vez declarado, podremos extraer de una URL partes de la misma. Para realizar esta extración usamos la propiedad gw.pathParams.
var route = new Route({path:'/:var1/:var2'},function(gw){
gw.json(gw.pathParams);
});
//Consultando localhost:300/users/john imprime:
//>{var1: 'users', var2:'john'}

Para simplificar la metodología de trabajo con la información que llega en la petición. Tanto el query string (GET), como el contenido de la petición (POST) y las rutas parametrizadas, se encuentran también seteados en gw.params. Esto es una copia, simplemente más accesible de todos los datos obtenidos en la solicitud.

Volver arriba