NEWS: Proxy capability added: see achieve-proxy.
Achieve is a modern (http, https, http2) high-performance, developer friendly web server that runs on Node.js and uses JavaScript Servlets to initiate back end processing.
This is a quick-start guide. If you need more help getting started, from using localhost and local IP addresses to obtaining security certificates and forwarding ports, click here.
Achieve is part of the High Level Logic Project.
- Delivers static content.
- Unlimited MIME support.
- Runs back-end JavaScript programs (via JavaScript Servlets).
- Supports defaults index.html, index.htm, index.js
- Supports browser caching. (ETag)
- Supports compression with ss caching. (gzip,deflate)
- Streaming audio/video files.
- No knowledge of Node.js required to start using JS Servlets.
- Little knowledge of JavaScript required to start using JS Servlets.
- Servlets handle HTTP/S Response. App just uses return statement.
- Useful app error reports can be displayed in browser console.
- Automatic reload of modified files.
- Servlet Session Object allows developer to take complete control.
- Node.js environment configuration. (development,production)
- Configurable apps folder path and path to the ROOT application.
Install Node.js
const server = require('achieve');
server.listen(); // defaults to port 80
By default, the base application directory is the same as the file you create to start the server. You can set the base application directory with the setAppPath option below.
const server = require('achieve');
server.setAppPath("c:/myachieve/myapps"); // set base directory for all applications
server.setRootDir('root'); // set a subdirectory under the root directory for THE ROOT application
server.setCaching(true); // turn browser caching support on
server.setCompress(true); // compress static resources
server.showMimeTypes(); // Show the current list of supported MIME Types
server.addMimeType("pub","application/x-mspublisher"); // add an unsupported MIME type
server.addAVMimeType("wav","audio/wav"); // add an unsupported AV MIME type
server.setNodeEnv("development"); // set Node environment
server.listen(8989); // listens on port 8989
// Save this code in file index.js in the apps directory ("application base" - directory where you are running the server)
exports.servlet = function (session) {
return "Hello World!"; // Achieve handles the response.
}
Display results in browser: http://localhost:8989 (assuming port 8989 and the file is named index.js.
Note also that the url is index, without the .js extension. With the .js extension, http://localhost:8989/index.js the file will be served.
Achieve will reload your programs when they've been modified. No need to restart the server.
Modify your servlet to cause an error by deleting a few characters from the end of the return statement:
return "Hello World. Refresh the page.
To see how to receive error message in the browser's console, save this HTML file and save it to your apps directory as index.htm. Open the inspector in your browser and click on the console tab. Then reload http://localhost:8989 On the browser side, the trick is in the callback() function.
var myParm = session.params.myParm; // or
var myParm = session.params['myParm'];
exports.servlet = function (session) {
return hello();
}
function hello () {
return "Hello World!";
}
// in otherfile.js
exports.hello () {
Return "Hello World!";
}
// in myservlet.js
exports.servlet = function (session) {
var other = session.load("otherfile.js"); // Extends servlet features to otherfile; reloads if cache is stale.
return other.hello();
}
You can use the Servlet Session to take control of your back end process. The Servlet Session contains:
session.request // The session request object.
session.response // The session response object.
session.params // Parameters sent with the request
session.dirPath // The current application path on your computer
session.load // The JavaScript Servlet load() method (see above)
session.allowAsync // Set to true if you handle the response in an asynchronous process.
Using HTTPS on Achieve is actually quite simple. It shares configuration set-ups with Achieve HTTP. The difference is in the listen methods. Achieve HTTPS has its own, called slisten(). slisten() requires a JSObject as input, which lists your security certificates. Security certificates, and how to obtain them (cost free) is explained below.
const server = require('achieve');
const fs = require('fs');
const options = { // An easy way to acquire free certificates is explained below.
key: fs.readFileSync('C:/certs/private.key'), // For certificate files that have been placed in C:/certs/
ca: fs.readFileSync('C:/certs/bundle.crt'), // optional, provides "full chain" of certificates
cert: fs.readFileSync('C:/certs/certificate.crt')
};
server.slisten(options);
Port 443 is the default port for HTTPS. If you need to use a different port, add the port number to the options object.
const options = {
key: fs.readFileSync('C:/certs/private.key'),
ca: fs.readFileSync('C:/certs/bundle.crt'), // optional
cert: fs.readFileSync('C:/certs/certificate.crt'),
httpsPort: 7777
};
Install Node.js v10.16.0 or later.
Using HTTP2 on Achieve is also easy. It shares configuration set-ups with Achieve HTTP/S. It also has its own listen method - listen2(). You may use HTTP2 without encryption and without security certificates. Simply follow instructions for HTTP above, but using .listen2() rather than .listen(). Note however that browsers are not accepting unencrypted traffic on HTTP2. If your target client is a web browser, or if you need secure connections with other clients, follow the instructions for HTTPS above (using .listen2()), but with the port property name http2Port. Achieve HTTP2 requires Node.js v10.16.0 or higher.
copyright © 2020, Roger F. Gay, may be freely distributed with the MIT license