All field notes

Productivity · Retrospective

The backend checklist I wrote into a TriveAcademy internship tutorial

A clipboard with a column of twelve blue dots beside a small white server.
Concept illustration · AI-generated

At the end of March I started a public repository for TriveAcademy interns, the internship tutorial. The application is deliberately dull: a to-do list API with staff accounts. The point is the list at the top of its README. It has twelve lines, and each one is a habit I would otherwise end up explaining in code review, one pull request at a time.

As the founder of TriveAcademy, I would rather write those habits down once, in code that runs. Most of the code went in over two days at the turn of the month, and CI followed in mid-April.

Validate at the edge, query with parameters

Every route declares what it accepts with Joi: a username and password for login, an integer for a to-do ID, an authorisation header for anything protected. A request that does not match is rejected before the handler runs, so the handler can trust its inputs.

Behind the handlers, every query passes values as parameters ($1, $2) instead of building SQL strings. An early commit used an escaping library, and in the next commit I replaced it with the PostgreSQL driver's own parameter handling. Escaping is something you can forget once. Parameters are the default.

Authentication on by default

The server registers JWT authentication as the default strategy, so every route is protected unless it says otherwise. Only login and register opt out. Passwords are hashed with bcrypt, and a failed login returns the same message whether the username or the password was wrong, so the endpoint does not confirm which accounts exist.

The token carries a session ID, and the server trusts nothing else in it. On login, the server writes a session row to PostgreSQL with the client's IP address, and stores the user's name and scope in Redis under that session ID. On each request, the validation function reads the session from Redis instead of querying PostgreSQL every time. Two things follow. A session can be ended on the server by deleting one key, without waiting for a token to run out. And a user's role is whatever the server holds now, not whatever was true when the token was signed. Routes then check that role: listing every to-do requires the admin scope.

Routes that document themselves

Hapi Swagger builds the API documentation from the route definitions: the description, the tags and the Joi schemas already written for validation. Nobody maintains a separate document that drifts away from the code.

Style and CI before features

ESLint with the Standard rules, together with Prettier, settles formatting questions before anyone asks them. In mid-April I added Travis CI, which installs the dependencies and runs the linter on every push, and CircleCI alongside it. The README says why there are two: Travis is free for open-source repositories, and CircleCI has a free tier that also covers private ones. The tutorial shows a route for either kind of repository.

Why the database wrapper became a package

The tutorial connects to PostgreSQL through hapi-pgsql, a small Hapi plugin I published to npm at the turn of March and April. The plugin I had used before did not fit the newer Hapi plugin structure, and copying connection code into every project is how small differences creep in.

The plugin creates a connection pool when the server starts, makes it available on every request as request.pgsql, and closes it when the server stops. Its log line names the user, host and database, and leaves the password out. Because it is a package, it carries its own tests, and its test command fails if coverage drops below 100%. That is a standard I can hold a library this small to. Holding a whole application to it is a different conversation.

I held my own protocol work to the same list this month. The TriveAsset protocol gained tests and documentation before I published it to npm in mid-April.

What the checklist does not cover yet

The tutorial has no tests of its own. Its CI step runs the linter, and the test script is a placeholder. Tokens and sessions have no expiry. Those are the next points the checklist needs, and I would flag both in any review of code built from it.

A checklist like this is not a style preference. Each line removes a decision someone would otherwise make under deadline: whether to validate this input, whether to escape that string, whether this route needs a login. Making the safe answer the default is cheaper than reviewing for it afterwards.