diff --git a/changes.md b/changes.md index 8c8bcdd1..9622c8d7 100644 --- a/changes.md +++ b/changes.md @@ -1,6 +1,7 @@ # Change Log ## v3.2.1 + Adds a log entry with default of console.log in the config object. This lets you provide a logger for use with the internal log messages in monument. It also makes testing a little cleaner. @@ -15,9 +16,11 @@ It also cleans up a huge swath of typos and make the documentation and testing generally better. ## v2.6.0 + Adds statsd support! ### statsd + There is now the option to pass in config for statsd to the config object. This will send timing info and stats for all route requests to the configured statsd server. Handy for all sorts of things and pretty much free for you work wise. The statsd client defaults to caching the DNS for the statsd server and to port 8125 so all you really need to do is pass in the host. You can also pass a prefix and suffix which will be passed along to `node-statsd` which is what we are using under the hood. @@ -27,33 +30,41 @@ If you have other statsd info/metrics that you would like to collect let us know Other then that there isn't really anything that has changed at all! ## v2.5.0 + Another successful minor release! ### connection.res.setStatus + There is now a chainable convenience function for setting the status and statusMessage headers. It uses the HTTP_STATUS object that is part of node's core http to make sure the messages and codes are aligned. For more information on using it check out the [writing route handlers](docs/writing-route-handlers.md) docment! ### Updates dependencies + Brings us up to date with the latest versions of all the dev and non-dev dependencies. This is a much smaller minor release then 2.4.0 was but we couldn't add the setStatus API in a patch :-) ## v2.4.1 + This is a minor patch with test expansion and documentation updates. Nothing risky or terrifying. The tests have been expanded to cover config options for dotjs. ## v2.4.0 + Minor release time! ### Brötli Compression + Starting with this release brötli compression is supported for both static and dynamic requests. It is amazingly tight compression that beats out gzip and deflate. To keep it snappy we are using a wrapper around the `c` implementation instead of a pure `js` implementation. Brötli does have one quirk, that it is only supported by browsers over https. So make sure you have https setup if you are going to use it. `monument` itself doesn't care, meaning that you could have monument speaking `http` behind an `https` load balancer and it will still serve up brötli if the browser supports it. But if you are running the `https` right off of `monument` make sure that you are passing in the `https` module to `server` in the config object. It should also work with `http2` or `spdy` which require certificates as well. ### Higher performance web sockets + This release also adds a couple of binary dependencies that improve the performance of the `ws` library. See [the ws docs](https://www.npmjs.com/package/ws#opt-in-for-performance) for more details about that. ### Router API! + There is now a route decleration API so that you can easily add and remove route handlers to the server while it is running. This is awesome! Not only does it provide a code-over-config option for creating route handlers it also makes it possible to create and destroy them as needed. For more information check out the [documentation](https://github.com/ansble/monument/blob/master/docs/routes.md). @@ -77,6 +88,7 @@ The big enhancement for Liège–Bastogne–Liège (2.3.0) is the addition of fi ### New form handling information The files that are uploaded are sent to the OS's temp file directory and the object that contains the references to them looks like this: + ``` { "file1": { @@ -94,9 +106,10 @@ The last real notable change is the addition of some more information around con ## v2.2.0 -The main focus of this release is expanding the available protocol stack that `monument` can use to communicate. It adds a builtin Web Socket server and the ability to drop in any http-like server that adheres to the API made popular by the builtin `http` and `https` modules. This includes `spdy` and `http2`! +The main focus of this release is expanding the available protocol stack that `monument` can use to communicate. It adds a built-in Web Socket server and the ability to drop in any http-like server that adheres to the API made popular by the built-in `http` and `https` modules. This includes `spdy` and `http2`! ### Config changes: + Current state of the config object is right below this. Explanations about the new items in the server section of the config is below. ``` @@ -118,7 +131,7 @@ Current state of the config object is right below this. Explanations about the n , noSniff: true //default, can be set to false to disable , frameguard: { action: 'SAMEORIGIN' //the default allows iframes from same domain - , domain: '' //defaults to not used. Only used for 'ALLOW-ORIGIN' + , domain: '' //defaults to not used. Only used for 'ALLOW-ORIGIN' } , hsts: { maxAge: 86400 // defaults to 1 day in seconds. All times in seconds @@ -137,7 +150,7 @@ Current state of the config object is right below this. Explanations about the n defaultSrc: `'self'` // optional. This is the default setting and is very strict } } - + // Web Sockets is new for this release! , webSockets: false // default setting disables websockets. can be (false, true, 'passthrough', 'data') @@ -152,7 +165,8 @@ Current state of the config object is right below this. Explanations about the n ``` #### Web Sockets -Web Sockets are awesome and generally pretty straightforward. `monument` does have some opinions about how to handle them and the settings allow for quite a bit of flexibility when it comes down to it so let's take a deep dive into working with them. If you aren't familiar with how web sockets work the [HTML5 rocks article](http://www.html5rocks.com/en/tutorials/websockets/basics/) is a good place to start. + +Web Sockets are awesome and generally pretty straightforward. `monument` does have some opinions about how to handle them and the settings allow for quite a bit of flexibility when it comes down to it so let's take a deep dive into working with them. If you aren't familiar with how web sockets work the [HTML5 rocks article](http://www.html5rocks.com/en/tutorials/websockets/basics/) is a good place to start. Web Sockets allow a low latency, low overhead two-way connection between youe client and server. It dramatically reduces the overhead of normal connections, by staying open and by not involving the transmission of headers with every piece of data. They are pretty fantastic. @@ -161,10 +175,11 @@ The idea of events or messages in Web Sockets meshes very well with `monument`'s ##### Settings There are four possible settings for web socket config. -- `false` which turns off the web socket server -- `true` which turns it on with `data` and `passthrough` style handling enabled -- `data` which turns on the server but only for `data` style handling -- `passthrough` which turn on the server but only for `passthrough` style handling + +- `false` which turns off the web socket server +- `true` which turns it on with `data` and `passthrough` style handling enabled +- `data` which turns on the server but only for `data` style handling +- `passthrough` which turn on the server but only for `passthrough` style handling Any other value passed to the `config.webSocket` will be treated as `true` turning on the server for both handlings. The default setting is `false`. @@ -245,7 +260,7 @@ Current state of the config object is right below this. Explanations about the n , publicPath: './public' // the folder where your static files live , maxAge: 31536000 // time to cache static files client side in milliseconds , etags: true // turns on or off etag generation and headers - + //the security object is brand new in this release , security: { xssProtection: true //default, can be set to false to disable @@ -253,7 +268,7 @@ Current state of the config object is right below this. Explanations about the n , noSniff: true //default, can be set to false to disable , frameguard: { action: 'SAMEORIGIN' //the default allows iframes from same domain - , domain: '' //defaults to not used. Only used for 'ALLOW-ORIGIN' + , domain: '' //defaults to not used. Only used for 'ALLOW-ORIGIN' } , hsts: { maxAge: 86400 // defaults to 1 day in seconds. All times in seconds @@ -276,31 +291,38 @@ Current state of the config object is right below this. Explanations about the n ``` #### poweredBy + You can set this value to whatever you want it to look like your server is powered by. By default it is off and the server does not return the `X-Powered-By` header. This is more secure then specifying it so we receommend you leave this alone, but since you are an adult you are free to set a value here. Any string passed here will become the value of the `X-Powered-By` header. #### xssProtection + If set to false this turns off the X-XSS-Protection header for all browsers. This header is disabled in IE < 9 because it opens up vulnerabilities. In everything else it is enabled by default. #### noSniff + If set to false this turns off the X-Content-Type-Options header for all browsers. This header prevents browsers from trying to infer mime type when a file with a mime type is downloaded. This helps prevent download related vulnerabilities and the misinterpretation of file types. #### frameguard -Guard is a weird looking word. + +Guard is a weird looking word. Not that we have that out of the way frameguard allows you to specify under what conditions your application may be wrapped in an `iframe`. Setting `action: 'DENY'` means that your site may never be wrapped in an `iframe`. The default is 'SAMEORIGIN' which allows wrapping of your site by essentially your app. The last allowed setting, `action: 'ALLOW-ORIGIN'`, requires that you pass a `domain` value as well. It allows the specified domain to wrap your application in an iframe. All the calculations for `SAMEORIGIN` and `ALLOW-ORIGIN` follow the CORS rules for determining origin. So `www.designfrontier.net` and `designfrontier.net` are different origins. #### hsts (HTTP Strict Transport Security) -This tells browsers to require HTTPS security if the connection started out as an HTTPS connection. It does not force the connection to switch, it just requires all subsequent requests by the page to use HTTPS if the page was requested with HTTPS. To disable it set `config.security.hsts` to `false`. It is set with a `maxAge` much like caching. The `maxAge` is set in seconds (not ms) and must be a positive number. + +This tells browsers to require HTTPS security if the connection started out as an HTTPS connection. It does not force the connection to switch, it just requires all subsequent requests by the page to use HTTPS if the page was requested with HTTPS. To disable it set `config.security.hsts` to `false`. It is set with a `maxAge` much like caching. The `maxAge` is set in seconds (not ms) and must be a positive number. The two optional settings: `includeSubDomains` and `preload` are turned on by default. `includeSubDomains` requires any request to a subdmain of the current domain to be HTTPS as well. `preload` is a Google Chrome specific extension that allows you to submit your site for baked-into-the-browser HSTS. With it set you can submit your site to [this page](https://hstspreload.appspot.com/). Both of these can be individually turned off by setting them to false in the config object. For more information the spec is [available](http://tools.ietf.org/html/draft-ietf-websec-strict-transport-sec-04). #### noCache + Before using this think long and hard about it. It shuts down all client side caching for the server. All of it. As best as it can be shut down. You can set it to an object `{noEtag: true}` if you want to remove etags as well. If you merely set it to true then all no cache headers will be set but the ETag header will not be removed. There is now also a `res.noCache` function that allows you to do the same thing but on a per request/route/user (however you program it) basis. This is a much better option then setting noCache server wide. #### publicKeyPin + This one is a bit of a beast. Before setting it and using it please read: [the spec](https://tools.ietf.org/html/rfc7469), [this mdn article](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning) and [this tutorial](https://timtaubert.de/blog/2014/10/http-public-key-pinning-explained/). It's a great security feature to help prevent man in the middle attacks, but it is also complex. Enough of the warnings! How do you configure it? The config object above explains it pretty well. Some details about `includeSubdomains`: it pins all sub domains of your site if it is set to true. Turned off by setting it to false. @@ -335,27 +357,32 @@ This is the Content Security Policy configuration. Content Security Policies are Because of the extensive options available in configuring your CSP we recommend that you go take a look at [the MDN article on directives](https://developer.mozilla.org/en-US/docs/Web/Security/CSP/CSP_policy_directives). All of the options they spell out are supported. The directives need to be passed in camelCase though (`defaultSrc` not `default-src`). -The default is a very strict `default-src 'self'` which prevents any files from outside the current domain from being loaded and/or executed. You will probably want to ease that off a hair. +The default is a very strict `default-src 'self'` which prevents any files from outside the current domain from being loaded and/or executed. You will probably want to ease that off a hair. In the event that you don't want a Content Security Policy (why!? WHY!? Trust us you want one) you can disable it by setting `config.security.contentSecurity` to false in the config section of your server. This is not a good idea. ## v2.0.0! + Despite it being a major release this is actually a pretty bland one. It's a major release because monument 2+ requires you to be running on node > 4.0.0. It is a rewrite and cleanup in ES6 syntax. There will likely be a few more tweaks over the next couple of days, but this is a nice stable release as is. ### Performance + One of the things that did change was how route detection works. It now uses better Array functions instead of forEach, and filter in most places. Array.find has taken over the routing functions which means they exit quicker. This is a minor performance tweak, and the chances of you noticing it are tiny. But, for apps with large route lists this will make a difference, maybe even a big one. ### Testing + We are now over 80% global coverage and have a rule in the build to require we hit 80%. So going forward that number will move upwards and the system as a whole will be more stable. ### Components + We now use [harken](https://github.com/ansble/harken) to handle events. Pulled it out of this code base and made it its own thing, much like event-state in a previous release. Makes the codebase simpler. This also means that you can use the same event system in your clients now. Which is pretty sweet. This release breaks the router into a whole lot of smaller components. This is for testability, and to make it easier to reason about what is happening in the router. Before this version the router was a black box with terrible testability. ### Better commmit messages! + The git log is now much nicer... ## Changes in 1.5.0 @@ -376,8 +403,8 @@ HEAD requests are now supported correctly for static resources. If you want to u That's the majority of the changes for 1.5.0! - ## New in 1.4.0 + This was essentially a patch that turned into a minor release. We found some issues with using the builtin node event system that seemed to be revving up memory usage like crazy and so we rewrote the whole event system to use a custom one. The API is identical to 1.3.0 but the 99% rewrite of a core module felt more like a minor release then a patch release. So the new for this release is pretty much transparent, but it is lower overhead for your application. Also updated all dependencies to latest. @@ -385,16 +412,19 @@ Also updated all dependencies to latest. ## New in 1.3.0! ### etags + Hash based etags are now available by default. You can turn them off by adding `'etags': false` to your config object (passed into `monument.server`). They are generated and used for all static files, and all responses that use `res.send`. One of the cooler things we did was have monumen cache the etags for static assets. That means they get created the first time they are requested after the server starts up, and for all subsequent requests the etag is pulled from an in memory cache so that the file i/o is only done if there is a reason to stream the file to the client. Makes them fast and light! ### `.send()` + One of the things that I heard from several users was the lack of response.send was confusing for them. So we added it! It also allows etags and automatically handles strings or objects correctly. Basically it is a nice layer of sugar around res.end and res.setHeaders that correctly handles mimetype and serializing the data if needed. Should make developing in monumet just a little easier. ### required events (state machine) + We pulled in [event-state](http://github.com/ansble/event-state) to provide a simple way to do something after multiple events have been fired. Its syntax is very simliar to `Promise.all` and it takes an array of events to listen for. ``` @@ -404,6 +434,7 @@ We pulled in [event-state](http://github.com/ansble/event-state) to provide a si ``` ### compression for static files + Deflate and gzip compression of static files is handled according to the accepts header from the client. We do it in a pretty slick way that writes out the compressed file to the file system at first request, reducing the computing required for serving them on subsequent requests as compressed files. Compression for non-static files is scheduled for the next release (1.4). You can turn compression on or off in the config object described below.