JSGI Requests and Responses

The JSGI (JavaScript Gateway Interface) specification defines an low-level interface between a HTTP server and JavaScript-based web applications. It has been developed by the CommonJS project and is implemented by Ringo. The main goal is to map incoming HTTP requests to arbitrary JavaScript objects. Application developers can use the request data, manipulate it, and generate a response object, which the JSGI implementation maps back to a valid HTTP response.

Between the HTTP server and the application, developers can include middleware functions. Middlewares can manipulate the request object, like parsing query parameters. They help to make application development easier. Web frameworks like stick provide a rich set of middlewares.

Request Object

• host — host name of the web server
• port — local port number of the web server
• queryString — query string of the URL, separated from the preceding path by a question mark
• version — HTTP version of the request in form of an array [majorVersion, minorVersion]
• remoteAddress — fully qualified name (FQDN) of the client's IPv6 or IPv4 address
• scheme — returns https for secure connections, http otherwise
• async — true if the request supports asynchronous operation
• headers — object containing the client-supplied HTTP request headers with lower-case keys; multiple header values will be merged following RFC 7230
• input — body of the request in binary form as io.Stream
• scriptName — empty string if the current JSGI application is the "root" of the server; the initial portion of the request URL's path that corresponds to the application object otherwise
• pathInfo — the URL's decoded path, always starting with a "/" character
• method — the name of the HTTP method; e.g. GET, HEAD, POST, PUT, DELETE
• env — Ringo-specific environment information
  • env.app — the module.id if the current JSGI application is a CommonJS module; not defined otherwise
  • env.servlet — the JSGIServlet instance handling this request
  • env.servletRequest — the original javax.servlet.http.HttpServletRequest instance provided by the Servlet container
  • env.servletResponse — the original javax.servlet.http.HttpServletResponse instance provided by the Servlet container
• jsgi — JSGI-specific read-only variables
  • jsgi.version — Ringo implements version 0.3
  • jsgi.multithread — Ringo supports multi-threading, always true
  • jsgi.multiprocess — Ringo is a single-process runtime, always false
  • jsgi.runOnce — Ringo might call a single JSGI application multiple times, always false
  • jsgi.cgi — Ringo runs atop Jetty or any other Servlet container, but not atop CGI, so always false
  • jsgi.errors — references system.stderr for error output

Response Object

A JSGI application is a JavaScript function accepting exactly one argument which is the request object. It must return a valid response object. The response object has exactly three required properties:

• status — a three-digit integer representing the HTTP response status code; e.g. 200
• headers — a JavaScript object containing key/value pairs with string or array values
• body — an array-like object implementing a forEach method, which will be called to generate a valid response. Each element must have a toByteString method or be an instance of Binary.