forked from mjackson/strata
-
Notifications
You must be signed in to change notification settings - Fork 0
/
SPEC
114 lines (90 loc) · 5.5 KB
/
SPEC
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
This specification aims to formalize the Strata protocol for building web
applications using the node.js JavaScript platform. You can (and should) use
the strata.lint middleware to enforce it. When you develop middleware, be sure
to add a strata.lint before and after to catch all mistakes.
# Applications
A Strata application is a function that takes exactly two arguments: the
*environment* and a *callback*.
## The Environment
The environment is an object that contains CGI-like properties. It MUST include
the following:
- protocol The request protocol (i.e. "http:" or "https:")
- protocolVersion The version of the protocol used in the request
- requestMethod The request method (e.g. "GET" or "POST")
- requestTime A Date that indicates the time the request was received
- serverName The host name of the server. Defaults to the value of
process.env.SERVER_NAME or the bound address of the server
as reported by the operating system.
- serverPort The TCP port the server is bound to. May be an empty
string when the server is using a UNIX socket.
- scriptName The initial portion of the request URL's "path" that
corresponds to the application, so that it knows its
virtual "location". This may be an empty string, if the
application corresponds to the "root" of the server.
- pathInfo The remainder of the request URL's "path", designating
the virtual "location" of the target resource within the
application. This may be an empty string if the request
URL targets the "root" of the application and does not
have a trailing slash. This value may be percent-encoded
when originating from a URL.
- queryString The portion of the request URL that follows the "?", if
any. May be an empty string.
- http* Variables corresponding to the client-supplied HTTP
request headers (i.e. variables whose names begin with
"http"). The presence or absence of these variables should
correspond with the presence or absence of the
appropriate HTTP header in the request. The remainder of
the property name will be the camel-cased version of the
original header name (e.g. "httpAccept" and
"httpUserAgent").
- input A readable Stream of data contained in the request body
- error A writable Stream for error output
- strataVersion The current version of Strata as [major, minor, patch]
In addition to these, the environment MAY include the following properties:
- session An object containing session data. Available to all
applications downstream from a strata.sessionCookie
- route An object containing information about the route that was
triggered. Available to all applications downstream from a
strata.Router
When combined with scriptName and pathInfo, the serverName and serverPort
variables may be used to reconstruct the original request URL. Note, however,
that if httpHost is present it should be used in preference to serverName.
The environment MUST NOT contain the properties httpContentType or
httpContentLength (use contentType and contentLength instead).
There are the following additional restrictions:
- protocol must be either "http:" or "https:"
- requestMethod must be a valid HTTP verb as an uppercase String
- requestTime must be a Date
- scriptName and pathInfo, if not empty, should start with a "/"
- scriptName should never be "/" but instead be empty
- pathInfo should be "/" if scriptName is empty
- contentLength, if given, must consist of digits only
- input must be a readable Stream
- error must be a writable Stream
- strataVersion must be an array of integers
The application is free to modify the environment. Property names must be
prefixed uniquely. The prefix "strata" is reserved for use within the Strata
core distribution and other accepted specifications and is not available for
use elsewhere.
## The Callback
The callback is used to issue a response to the client and must be called with
exactly three arguments: the response *status*, HTTP *headers*, and *body*.
### The Status
The status must be an HTTP status code as a Number.
### The Headers
The headers must be an object whose properties are the names of HTTP headers in
their canonical form (i.e. "Content-Type" instead of "content-type"). Header
names may contain only letters, digits, "-", and "_" and must start with a
letter and must not end with a "-" or "_". If more than one value for a header
is required, the value for that property must be an array.
There must be a Content-Type header, except for when the status is 1xx, 204, or
304, in which case there must be none given.
There must not be a Content-Length header when the status is 1xx, 204, or 304,
or it must be "0".
### The Body
The body must be either a string or a readable Stream. If it is a Stream, the
response will be pumped through to the client.
# Acknowledgements
Some parts of this specification are adopted from PEP333: Python Web Server
Gateway Interface v1.0 (http://www.python.org/dev/peps/pep-0333/) and the Rack
specification (http://rack.rubyforge.org/doc/files/SPEC.html).