Capstone C: the index over HTTP
Project C is the search index of project B behind an HTTP endpoint. A browser, a script and curl all speak the same protocol, so the index leaves the terminal and becomes something another program can call. The lesson is short because the hard part, the search, is already a function of its input.
The server of this lesson is one file. It starts on port 0, asks the operating system for the port it got, sends four requests to itself, prints the status and the body of each answer, and closes the server before the program ends. Port 0 is what makes the program runnable on a machine where 8080 is taken, and the self-probe is what makes the output of the page the real answer of a real server.
A copy of project B
The folder is named search-http and starts as a copy of the two folders of project B that hold code. The check program stays behind, because the server is now the program that runs and the tests of the search still cover the search.
mkdir search-http
cd search-http
cp -r ../search/src ../search/test .
The manifest is the one of project B under another name, and the lint config gains two names: fetch for the probe and URL for the request. Both are globals of the runtime and neither is a name the language has, so the linter has to be told.
The file package.json:
vi package.json
{
"name": "search-http",
"version": "1.0.0",
"description": "The search index behind an HTTP endpoint",
"type": "commonjs",
"scripts": {
"test": "node --test --test-reporter=dot",
"lint": "eslint ."
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"eslint": "^10.14.0"
}
}
The file eslint.config.js:
vi eslint.config.js
const js = require('@eslint/js');
module.exports = [
js.configs.recommended,
{
languageOptions: {
ecmaVersion: 'latest',
sourceType: 'commonjs',
globals: {
console: 'readonly',
fetch: 'readonly',
process: 'readonly',
URL: 'readonly',
},
},
},
];
The four modules of the search are copied and not rewritten, and so are the two test files. A project that starts from a copy is the normal case for a library with two consumers, and the copy is a snapshot: a fix to the index has to be made in both folders until the search becomes a package of its own.
The handler and the server
createServer takes one function and calls it for every request with the request and the response. The handler reads the path, decides what the answer is and ends the response; the server does the socket, the parsing and the keeping alive. The lesson on node:http builds the same pair with three routes.
The body of every answer is JSON, so send does the three steps once: writeHead with the status and the content type, end with the text, and JSON.stringify in between. A 204 would be an answer without a body; the reader of a 400 needs the text that says what was wrong.
The main function listens, reads the port from the server and loops over the four paths. The await on listen turns the callback into a promise, so the probe can run after the socket is ready; the same pattern closes the server at the end.
The file server.js:
vi server.js
const { createServer } = require('node:http');
const { DOCUMENTS } = require('./src/index');
const { createSearch } = require('./src/search');
const search = createSearch(DOCUMENTS);
function send(response, status, body) {
response.writeHead(status, { 'content-type': 'application/json' });
response.end(JSON.stringify(body));
}
function handler(request, response) {
const url = new URL(request.url, 'http://127.0.0.1');
if (url.pathname !== '/search') {
send(response, 404, { error: 'not found', path: url.pathname });
return;
}
const q = url.searchParams.get('q');
if (q === null || q.trim() === '') {
send(response, 400, { error: 'the q parameter is missing or empty' });
return;
}
const results = search.find(q);
send(response, 200, {
query: q,
count: results.length,
hits: results.map((result) => ({ id: result.id, score: result.score })),
});
}
async function main() {
const server = createServer(handler);
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
const { port } = server.address();
const base = 'http://127.0.0.1:' + port;
for (const path of ['/search?q=cat+mat', '/search?q=slept', '/search?q=', '/nothing']) {
const answer = await fetch(base + path);
console.log(answer.status + ' ' + path);
console.log(' ' + (await answer.text()));
}
await new Promise((resolve) => server.close(resolve));
console.log('the server is closed');
}
main().catch((error) => {
console.error('error: ' + error.message);
process.exitCode = 1;
});
request.url is a path and not an absolute URL, which is why the URL constructor gets a base. The base is thrown away and its only job is to make the parser accept the relative path, so it can be any host.
The route and the answer
There is one route and one query parameter. /search with a q that is not empty gets the results of the search module, and the answer holds the query as the server read it, the number of results and the results themselves as id and score.
The titles stay out of the answer on purpose. They belong to the documents, they are long, and a client that wants them can ask for them by id; the endpoint is a search and its answer is a list of hits. That is also what keeps the line of the page short enough to read.
The query string is decoded by URLSearchParams, so cat+mat becomes cat mat and a %20 works as well. The module then tokenizes the text, which means the endpoint accepts the same query as the terminal and ignores case and stop words in the same way.
400 and 404
Two answers are not a search result. A path that is not /search is a 404, and a q that is missing or empty is a 400, because the request is well formed and its content is not: the client has to change what it sent, and the status says so.
The order of the two checks matters. The path is checked first, so a request to another route gets a 404 and never a 400 about a parameter that the route does not have. A handler that read q first would answer 400 to /health.
Both errors answer JSON with an error field, so a client parses every answer with the same code and reads the status for the branch. The exercise at the end asks for the retry-after header of a 503, which is the next step of the same idea.
node --check server.js
node server.js
node --test --test-reporter=dot
echo "the exit status: $?"
npx eslint .
echo "the lint status: $?"
200 /search?q=cat+mat
{"query":"cat mat","count":2,"hits":[{"id":1,"score":4},{"id":3,"score":2}]}
200 /search?q=slept
{"query":"slept","count":2,"hits":[{"id":1,"score":1},{"id":2,"score":1}]}
400 /search?q=
{"error":"the q parameter is missing or empty"}
404 /nothing
{"error":"not found","path":"/nothing"}
the server is closed
............
the exit status: 0
the lint status: 0
The four requests answer 200, 200, 400 and 404, and the bodies are the JSON of each case. The two first lines are the same order as the check of project B, which is the point of the copy: the endpoint and the terminal agree because they call the same function.
The twelve dots are the tests of the search, which run in this folder without a server. The last two zeros are the status of the runner and of the linter, and the port that the program used never appears in the output, because the program prints no address at all.
Exercises
- Add a /health route that answers {"status":"ok"}. Which branch of the handler does it need, and which status?
- Send a request with ?q= and one with no query string at all. Do the two get the same answer, and which line of the handler decides it?
- Make the answer hold the titles as well. Which function of the search would the handler need, and how many bytes does the answer of the first query grow by?
- Send a POST to /search and read the status. Which status would be right, and where would the method be read?
- Ask for the document 1 with /document/1 and answer 404 until the route is written. Which part of the URL names the id, and which parse turns it into a number?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does a server on port 0 let the operating system choose?
Answer
A free port, which the program then reads from the server
Port 0 asks for any free port, and address() answers which one it became.
-
What does this program print?
const url = new URL("http://127.0.0.1/search?q=cat+mat"); console.log(url.pathname, url.searchParams.get("q"));Answer
/search cat mat
The path is separate from the query, and a plus sign is a space in a query string.
-
Which status does a path that is not /search get?
Answer
404
The route does not exist, which is what 404 says.
-
What does this program print?
const url = new URL("http://x/search"); console.log(url.searchParams.get("q") === null);Answer
true
A parameter that is not in the query string answers null rather than an empty string.
-
Which status does an empty q parameter get?
Answer
400
The request is well formed and its content is not, which is the definition of a 400.
-
What does this program print?
const body = { query: "cat", count: 2, hits: [{ id: 1 }] }; console.log(JSON.stringify(body));Answer
{"query":"cat","count":2,"hits":[{"id":1}]}
The function writes every field and the array with its object inside.
-
Why is the path checked before the q parameter?
Answer
So another route gets a 404 and not a 400 about a parameter it does not have
The route decides which parameters exist, so the route is the first question.
-
What does
request.urlhold in a handler of node:http?Answer
The path and the query string, without the host
The host is in the Host header, so the URL constructor needs a base to parse the path.
-
What does this program print?
const url = new URL("http://x/search?q="); console.log(JSON.stringify(url.searchParams.get("q")));Answer
""
The parameter is there and holds an empty string, which JSON writes as two quotes.
-
Why does the program close the server before it ends?
Answer
An open server keeps the process alive and the program would never exit
The listening socket is a handle of the event loop, so the process waits for it.
The programs and commands on this page were run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container. The server listens on port 0, so no fixed port appears in its output.
Article author: Arthur Isaev