Use JavaScript and hapijs to build web applications. See the essentials of how to build hapi applications: authentication, validation, application architecture, and testing. Plus, delve into deeper topics like: bearer-tokens, caching, the request lifecycle.
First, we need some basic structure: a lib folder, a package.json file, and an initial ./lib/index.js.
Since we will be using hapi, we need to include that in the project dependencies.
Second, create a basic hapi server on port 8000 which responds to /version requests and replies with a simple { "version": "0.1.1" } JSON payload. The version data in the response should come from the package.json file.
npm init
npm install --save hapi
Above assignment is from original assignment1 by @hueniverse and work by @AdriVanHoudt. See this PR.
The right way to work with hapi is to build your application using plugins. Plugins provide a way to organize your code into logical components and then put them together in different combinations or deploy them in different configurations. While some plugins are published as general purpose utilities (e.g. adding authentication), you should think of plugins as a way to break your code into pieces.
Now that we have a basic server with one endpoint, we want to move the creation of the endpoint to a plugin,
and then register that plugin with the server. Create a new file lib/version.js and move the /version endpoint there.
Then, change our current lib/index.js to require the new plugin file and register the version plugin with our server.
The server.register() function is used to register the plugin.
Remember to follow the style guide, and ask any questions in the comments of the issue created for the assignment. If you are not sure how to get your fork back in sync with the current updated code, use the git guide.
/version end point should reply with a simple JSON payload:
{
version: Package.version,
message: options.message
}const plugins = [] is an array. An array is used to register the Version plugin because more plugins are to be registered in later assignments.{ message: 'assignment2' }.
The /version point returns the message value.server.register options are passed: { once: true }.
Often there is confusion between hapi's server.register options and options passed to a plugin being registered.
lesson2 clearly shows the difference. { message: 'assingment2' } illustrates options passed
to a plugin. These are options used inside the Version plugin. And, the { once: true } option is passed to the server
when registering plugins: server.register(). See /lib/index.js for details.require('./version') should be declared at the top and assigned toVersion`.compare assignment2 solution to assignment1
view assignment2 solution source
This assignment is from the original assignment2 convert to plugin and discussion related to the assignment written by @hueniverse. The code solution is from work done by @MylesBorins.
Things are getting a bit more interesting...
It's time to add tests, verify coverage, confirm style, and automate all of this with CI (CI means: Continuous Integration). We will be using the lab module to perform these tasks and automate them with travis. Code will be our test's assertian library.
init() and move the server invocation to a new lib/start.js file.
The lib/start.js file calls the exported init() function and passes configurations options to it.
The resolved promise function in start.js outputs the server config details to the console.
Change package.json file to use start.js as the start up script. start.js file is not covered by tests.
Designing the server to start with an exported init function allows other scripts and applications to start and stop the server.
This is important for several reasons:
start.js script to start and stop the application..travis.yml file. When a .travis.yml file exists in a GitHub repository the project is built and all tests are executed. .travis reports if all tests successfully pass or not.
Note, you must configure github to excute travis CI upon
events (push or PR) to the repository. This is found under: Settings -> Integration & Services.version.js and index.js, each testing the corresponding file under /lib.package.json file to include tests. Install the dev dependencies lab and code.package.json file to view the test command or see a test command write up here.version.js.lab confirms if the project's code abides by the hapijs style guide.
This is called 'linting'.Everything should be pretty straight forward. If you are not sure on how to use lab and code, look at other hapi.js modules and copy their test scripts and setup.
Getting 100% coverage can be tricky sometimes so if you are not sure, get as much coverage as you can, and comment on the lines in your pull request where you are having a hard time reaching and someone will give you a clue.
Remember to properly stop() your servers when calling the init() method in each test.
For now, avoid using any of the before() and after() lab features.
As always, ask for help and help others!
{ parallel: false } lab option to make it both safe for future parallel testing as well as visual cue.Error as an error (e.g. no strings, plain objects, etc.).0 or the default.return before next() unless there is a reason to continue.init() required.server.inject() with a GET request, just pass the path string as the first argument instead of an options object. Makes the code much more readable.Compare Assignment3 Solution to Assignment2
view assignment3 solution source
Assignment is from original assignment3 and discussion related to it.
The author was @hueniverse.
Original code for the solution was written by idanwe.
See: PR for original source code for solution.
The .travis.yml file is from the hapi project.
server.app propertiesserver.app property to store the application's response.version and options.message.request.server property in the ./lib/version.js handler to return the
server.app.version and server.app.message values.server.app property is useful to set a DB connections in. server.app properties
are available wherever the request.server is exposed.
As the documentation says:
server.appprovides a place to store run-time application data. Data can be accessible wherever the server object can be accessed.
Compare Assignment4 Solution to Assignment3
/version route handler function location.
The goal is design program code that is easy to maintain and reuse.
Moving route functions from the plugin which registers routes makes for readable route registration plugins.
Plus, it allows for easier maintenance and reuse of methods or functions.
request-lifecycle more.server.app properties../lib/route-methods.
Methods used in routes will be stored in this directory.version.js file in the route-methods directory ./lib/route-methods/version.js/version route will be stored here./version handler function to this file../lib/version.js./lib/route-methods/version.js1.0.5. Executing passing tests
proves changes did not break the application. Enjoy the benefits of CI Continuous Integration.Compare Assignment5 Solution to Assignment4
npm install --save hapi-auth-bearer-token./lib/authtoken.js./version.1234574/version tests for token authentication.
Test for passing and failing tokens.Notice we have not created user authentication yet -- users have no way to log in.
Tests for the assignment assume a valid auth bearer token for the user already exists.
The focus is on getting hapi auth bearer token plugin installed and configured.
This lesson does not build a complete authentication system.
Here are resources related to auth bearer tokens. Please share if you know of other links and resources related to the subject.
Compare Assignment6 Solution to Assignment5
This assignment started as assignment4.
It contains good discussion regarding authentication issues. For the original solution see: PR.
It used hapi-auth-basic.
Original TLS assignment completed by @rutaihwa.
Compare Assignment7 Solution to Assignment6
./authenticate route.database.js to authenticate user records with.
User records contain scope values to implement hapi's way of doing RBAC (role based access control).
For this project their are two scopes: ['admin', 'member']. admin is administrative user and member is
a normal user./authenticate route are stored in the ./route-methods/authenticate.js file.
This seprates logic:
./lib/version.js contains route registration logic../route-methods/authenticate.js contains methods executed in the route./authenticate route utilizes hapi's prerequisite request-lifecycle extension. The pre method is executed
before the handler.Request-lifecycle extensions allows for logic to be split up into multiple functions
and be executed at specific times when a request is made to a route.
In respect to route.options.pre methods,
These methods allow breaking the handler logic into smaller, reusable components that can be shared across routes, as well as provide a cleaner error handling of prerequisite operations (e.g. load required reference data from a database). Source: route.options.pre
See other documentation for more about the request lifecycle:
The request lifecycle is an essential part of the hapi framework. As the documentation says: "Every incoming request passes through the request lifecycle". Therefore, you want to be familiar with it.
/authenticate point.Compare Assignment8 Solution to Assignment7
This lesson completes a basic token based authentication system. Currently, our server only has two routes: /version and /authenticate.
Only users with authentic bearer tokens can access server routes. See token strategy in: ./lib/authtoken.js. The lib/authtoken.js strategy
is crude supporting one static token. On the /authenticate route we turn off the requirement for an authentic bearer token
with the false option because unauthenticated users do not have bearer tokens yet. The false option exposes routes to
public unauthenticated users.
At this point, there is a disconnect in the system. A user can generate a valid auth token on the /authenticate route.
But, that token is not stored for future use. As stated earlier, the authentication strategy only considers one token as valid (1234574).
To resolve this issue we use redisdb and hapi's caching plugins.
First, configure a bearer token cache. When a user successfully authenticates, the auth-bearer-token
generated for the session is stored in the cache catabox-redis.
Along with the token, the authenticated user account data is also stored in the cache. This is where a users scopes
are stored. Scope values determine which routes a user can access.
Second, the validateFunction for the auth-bearer-token strategy is modified to use the bearer token cache to validate received tokens.
This solves the above mentioned disconnect in our bearer token system.
Third, we create a /private route which requires administrative user privileges (admin scope) to access route data.
./lib/tokencache.js plugin../lib/route-methods/authenticate.js..travis.yml to use the redis serveractive cache. active cache is configured in ./lib/tokencache.js.authtokens cache. authtokens cache configured in ./lib/tokencache.js../lib/route-methods/authenticate.js logic is where new auth-tokens are stored in the cached upon successful authentication.
Plus, logic to pre-empt the creation of duplicate tokens is written here too.lib/authtoken.js
defaultValidateFunc to use the catbox-redis cache to authenticate tokens.Configs to set the tokencache.js plugin options.
This allows for test configurations to be modified. Our test configurations modify token
expiration times so tokens from different tests do not collide. See: ./lib/start.js const Configs.plugins.tokenCache.expiresIn.{ debug: false } to your server configs.
This avoids hapi-auth-bearer-token printing verbose error reports..travis.yml implementing redisdb is from: catbox-redis project.