Node.js MapCache Tile Caching Module
This module provides a map tile caching solution for Node.js by creating bindings to Mapserver Mapcache.
Mapserver MapCache is already deployable as an Apache/Ngnix module and CGI/FastCGI binary. This package makes accessing the MapCache functionality possible from Node with the following advantages:
- Flexibility: it makes it easy to add tile caching functionality to existing Node projects and isn't automatically bound to an HTTP environment.
- Control: full control over http headers and status codes is available allowing fine tuning of things like HTTP caching. URL end points can be defined as required.
- Robustness: The module has a suite of tests that exercises the whole API. The tests provide 88% line coverage and 91% function coverage; excluded code generally handles hard to replicate edge cases (e.g. memory exhaustion). This suite has been run through Valgrind to check for memory leaks.
Usage
The node-mapcache
API is designed to be simple but flexible. It binds into
the underlying libmapcache
library before the HTTP layer and around the
concept of a MapCache
object. A MapCache
instance is derived from a
standard mapcache configuration file. It is used to make requests to the
underlying tile cache and return the response:
var mapcache = // node-mapcache events = // for the logger logger = fs = ; // for filesystem operations // Handle log messageslogger; // Instantiate a MapCache cache object from the configuration filemapcacheMapCache;
The cache response (cacheResponse
in the above snippet) is a javascript
object literal with the following properties:
code
: an integer representing the HTTP status codemtime
: a date representing the last modified timedata
: aBuffer
object representing the cached dataheaders
: the HTTP headers as an object literal
The logger passed to FromConfigFile
above is optional: the method accepts
just two arguments as well. If a logger is passed in it is used for the life
of the MapCache
instance. The available log levels are the same as those in
the MapCache configuration file. From the Node REPL:
> var mapcache = require('mapcache');
> mapcache.logLevels
{ DEBUG: 0,
INFO: 1,
NOTICE: 2,
WARN: 3,
ERROR: 4,
CRIT: 5,
ALERT: 6,
EMERG: 7 }
Versioning information is also available:
> var mapcache = require('mapcache');
> mapcache.versions
{ node_mapcache: '0.1.5',
mapcache: '0.5-dev',
apr: '1.4.5' }
Example
This provides an example of how to use the MapCache module in combination with
the Node HTTP module to create a tile caching server. It is available in the
package as examples/server.js
.
var path = // for file path manipulations http = // for the http server url = // for url parsing events = // for the logger logger = mapcache = // the MapCache module port = 3000 // which port will the server run on? baseUrl = "http://localhost:" + port // what is the server url? conffile = path; // the location of the config file // Handle log messageslogger; // Instantiate a MapCache cache object from the configuration filemapcacheMapCache;
Another example is provided as examples/display.js
which pipes the output of
a cache request to the ImageMagick display
program.
Requirements
-
Linux OS (although it should work on other Unices and ports to Windows and other platforms supported by both Node and Mapserver should be possible: patches welcome!)
-
Node.js >=0.8
-
Mapserver MapCache 0.5-dev >= commit 11e8509
Installation
-
Ensure Mapserver Mapcache is installed. It should be built from source as we need the build directory in the next step:
-
Point node-mapcache to the MapCache build directory. These are not installed in the system by MapCache so a valid mapcache build directory must be provided. Assuming you built it in
/tmp/mapcache
you would use the following command:npm config set mapcache:build_dir /tmp/mapcache
-
Get and install node-mapcache:
npm install mapcache
-
Optionally test that everything is working as expected (recommended):
npm test mapcache
Recommendations
-
If you want raw speed use the Apache Mapcache module or reverse proxy your
node-mapcache
app with a web accelerator such as Varnish. Having said thatnode-mapcache
shouldn't be slow: benchmarks are welcome! -
When using the Berkeley DB (BDB) as a cache backend for multiple tilesets stability is improved by having a separate filesystem directory for each tileset: this seems to be because the BDB system files (e.g.
__db.001
) are created on a per directory basis and organising them discretely prevents them having to manage more than one BDB database. -
Check out
node-mapserv
: this can work well in combination withnode-mapcache
for generating tiled maps.
Contributing
Fork the code on GitHub or clone it:
git clone https://github.com/geo-data/node-mapcache.git
cd node-mapcache
Build the module in Debug mode using:
make build
By default this uses the mapcache build directory previously specified using
npm config set mapcache:build_dir
; to override this do something along the
following lines:
make build npm_config_mapcache_build_dir=/tmp/mapcache
You may want to ensure you're building in a clean source tree in which case:
make clean
Add tests for your changes to test/mapcache-test.js
and run them:
make test
Perform code coverage analysis to ensure all code paths in your changes are
tested (this requires lcov
be
installed):
make cover
Finally run the test suite through valgrind
to ensure you haven't introduced
any memory issues:
make valgrind
And issue your pull request or patch...
Documentation
Doxygen based documentation is available for the C++ bindings:
make doc
Bugs
Please add bugs or issues to the GitHub issue tracker.
Licence
Contact
Homme Zwaagstra hrz@geodata.soton.ac.uk