HTTP server

@delali/narsil/server puts a REST API in front of an engine that you build yourself, so the durability, the embedding adapters, and the worker threads stay under your control. You build one file here, server.ts, in which you start a server, admit only the callers that hold a token, and stop it so that the process exits. Each code block below holds the whole file, with green lines marking what each step adds and struck lines marking what it takes away.

Install the peer dependency

The server works on uWebSockets.js, which the package declares as an optional peer dependency, so install it from its GitHub release beside Narsil.

pnpm add -E uWebSockets.js@github:uNetworking/uWebSockets.js#v20.58.0

Start a server

createServer(engine, options) takes the engine and an address, and listen() resolves once the server accepts connections. A server bound to 127.0.0.1 accepts callers from the same machine alone, which suits a first run. The program then calls its own search endpoint, whose body takes the same options as query.

import { createNarsil } from '@delali/narsil'
import { createServer } from '@delali/narsil/server'
 
const engine = await createNarsil()
 
await engine.createIndex('articles', { schema: { title: 'string', body: 'string' } })
await engine.insertBatch('articles', [
  { id: 'refund-timing', title: 'How a refund reaches your bank', body: 'A refund returns to the card that paid for the order.' },
  { id: 'parcel-tracking', title: 'Track a parcel after dispatch', body: 'Every dispatched order has a tracking code.' },
])
 
const server = createServer(engine, { host: '127.0.0.1', port: 7700 })
 
await server.listen()
 
const response = await fetch('http://127.0.0.1:7700/indexes/articles/search', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ term: 'refund', document: { include: ['title'] } }),
})
 
console.log(response.status, JSON.stringify((await response.json()).hits))
 
await server.shutdown()

200 [{"id":"refund-timing","score":1.3862943611198906,"document":{"title":"How a refund reaches your bank"}}]

POST /indexes/articles/search answers with the same hits that query returns in process. server.shutdown() at the end stops the server and the engine together, which the last section explains.

Admit only the callers that hold a token

The server calls onRequest before every routed request with the method, the path, the headers keyed by lower-case name, and the peer address. Return a denial with a status, a code, and a message to refuse the request, or return undefined to let it through. Without an onRequest hook, createServer fails with CONFIG_INVALID for any address other than loopback, because the server's admin endpoints can drop, clear, and restore indexes. With allowInsecure: true the server skips that check on a trusted private network.

import { createNarsil } from '@delali/narsil'
import { createServer } from '@delali/narsil/server'
 
const engine = await createNarsil()
 
await engine.createIndex('articles', { schema: { title: 'string', body: 'string' } })
await engine.insertBatch('articles', [
  { id: 'refund-timing', title: 'How a refund reaches your bank', body: 'A refund returns to the card that paid for the order.' },
  { id: 'parcel-tracking', title: 'Track a parcel after dispatch', body: 'Every dispatched order has a tracking code.' },
])
 
const server = createServer(engine, { host: '127.0.0.1', port: 7700 }) 
const API_TOKEN = process.env.NARSIL_API_TOKEN ?? 'support-desk-token'
 
const server = createServer(engine, {
  host: '127.0.0.1',
  port: 7700,
  onRequest: (request) =>
    request.headers.authorization === `Bearer ${API_TOKEN}`
      ? undefined
      : { status: 401, code: 'UNAUTHORISED', message: 'Send the API token as a bearer token.' },
})
 
await server.listen()
 
const response = await fetch('http://127.0.0.1:7700/indexes/articles/search', { 
  method: 'POST', 
  headers: { 'content-type': 'application/json' }, 
  body: JSON.stringify({ term: 'refund', document: { include: ['title'] } }), 
}) 
const search = (token?: string): Promise<Response> =>
  fetch('http://127.0.0.1:7700/indexes/articles/search', {
    method: 'POST',
    headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
    body: JSON.stringify({ term: 'refund', document: { include: ['title'] } }),
  })
 
const denied = await search()
const allowed = await search(API_TOKEN)
 
console.log(response.status, JSON.stringify((await response.json()).hits)) 
console.log(denied.status, await denied.text()) 
console.log(allowed.status, JSON.stringify((await allowed.json()).hits))
 
await server.shutdown()

401 {"error":{"code":"UNAUTHORISED","message":"Send the API token as a bearer token."}}
200 [{"id":"refund-timing","score":1.3862943611198906,"document":{"title":"How a refund reaches your bank"}}]

The request with no token comes back 401 with the denial as its error envelope, while the request with the token gets the hits. /livez, /readyz, /health, /version, and /capabilities skip the hook, so that a load balancer can probe the server with no credentials.

Set limits before you open the address

With limits you cap what one caller can ask of the engine. The server answers a body larger than maxBodyBytes, 16 MiB by default, with 413 PAYLOAD_TOO_LARGE, and an offset past maxResultWindow, 10,000 by default, with 400 INVALID_REQUEST. Above maxConcurrentRequests, which defaults to 0 for no ceiling, the server sheds each request with 429 TOO_MANY_REQUESTS: in a measured run of 60 concurrent searches against a ceiling of 1, the server answered 30 and shed 30. cors names the origins that a browser may call from, and the server answers each preflight OPTIONS request with 204 and the allowed methods and headers.

An engine behind createServer sends every search to a worker copy once the index holds copies, because the server sets mainCopyQueries: 'none' where the engine leaves it unset. Call POST /indexes/{name}/_wait-for-writes between a write and a read that has to see it, for the reason that partitions and workers covers.

Stop the server so that the process exits

Each way of stopping a server that has served one search ends the process differently:

So call server.shutdown(), which stops the server and then the engine, before the process exits. A request that arrives while the server shuts down comes back 503 INSTANCE_SHUT_DOWN or fails to connect, depending on when it arrives, and listeningPort reads -1 once the server has stopped, so keep the port in a variable of your own.

See every endpoint

The endpoints that take a while, such as a rebalance, a rebuild, and an optimisation, answer 202 with a task record, which GET /tasks/{id} then reports on. The _multi-get body names its ids under docIds.

Where to go next

• Persistence and durability covers the durable engine that a server usually fronts.
• Language support covers the rebuild that _rebuild-analysis starts.