Introduction

Restana is a lightweight and fast Node.js framework for building RESTful APIs. Inspired by Express, it provides a simple and intuitive API for routing, handling requests and responses, and middleware management. It is designed to be easy to use and integrate with other Node.js modules, allowing developers to quickly build scalable and maintainable APIs.

Check it yourself: https://web-frameworks-benchmark.netlify.app/result?f=feathersjs,0http,koa,nestjs-express,express,sails,nestjs-fastify,restana,fastify

Express.js comparison (in the eyes of ChatGPT/OpenAI)

Restana and Express are both popular web frameworks for building REST APIs in Node.js.

Performance

Restana is a lightweight framework, offering faster performance than Express.
Express is more feature-rich and can handle complex applications, but this added functionality comes with a slight performance trade-off.

Speed of Development

Express has a larger community and more resources available, making it easier to find answers to development questions.
Restana is more straightforward and has a smaller learning curve, allowing for faster development of simple APIs.

Features

Express has a wide range of built-in features, such as routing, middleware, and template engines.
Restana focuses on simplicity and speed, offering basic features such as routing and middleware.

Ultimately, the choice between Restana and Express will depend on the specific requirements of a project.

Usage

Install

npm i restana

Create an HTTP API service:

const restana = require('restana')

const service = restana()
service.get('/hi', (req, res) => res.send('Hello World!'))

service.start(3000);

Creating secure API service:

const https = require('https')
const restana = require('restana')

const service = restana({
  server: https.createServer({
    key: keys.serviceKey,
    cert: keys.certificate
  })
})
service.get('/hi', (req, res) => res.send('Hello World!'))

service.start(3000);

Using http.createServer():

const http = require('http')
const restana = require('restana')

const service = restana()
service.get('/hi', (req, res) => res.send('Hello World!'))

http.createServer(service).listen(3000, '0.0.0.0')

Please take note that when using http.createServer() the service.close() feature is not available, since restana does not have access to http server instance.

Optionally, learn through examples:

Configuration options

server: Allows to optionally override the HTTP server instance to be used.
prioRequestsProcessing: If TRUE, HTTP requests processing/handling is prioritized using setImmediate. Default value: TRUE
defaultRoute: Optional route handler when no route match occurs. Default value: ((req, res) => res.send(404))
errorHandler: Optional global error handler function. Default value: (err, req, res) => { const statusCode = typeof (err.status || err.code || err.statusCode) === 'number' ? (err.status || err.code || err.statusCode) : 500; res.send({ code: statusCode, message: 'Internal Server Error' }, statusCode) }. The default handler returns a generic error message to prevent leaking sensitive internal details (e.g. database connection strings, file paths, stack traces). The appropriate HTTP status code is still preserved from err.status, err.code, or err.statusCode.
routerCacheSize: The router matching cache size, indicates how many request matches will be kept in memory. Default value: 2000
enableTrace: When TRUE, the TRACE HTTP method handler is available for debugging purposes. Default value: FALSE. ⚠️ Not recommended for production deployments.
securityHeaders: When TRUE, default security headers are set on every response. Set to FALSE to disable (e.g. when using Helmet or serving non-browser clients). Default value: TRUE.
trustProxy: When TRUE, trust the first X-Forwarded-Proto value when deciding whether to send HSTS. Only enable this behind a reverse proxy that replaces forwarded headers. Default value: FALSE.
debugErrors: When TRUE, res.send(error) includes error.message and error.data outside production. Use only for local debugging. Default value: FALSE.

Security defaults (v6.0+)

Restana now ships with these security hardening measures enabled by default:

Header injection protection: Security-sensitive and hop-by-hop headers are blocked from the res.send() headers parameter.
Error masking: res.send(err) masks the error message and strips err.data by default. Local development can opt in with debugErrors: true; production always masks details.
Default security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, and Strict-Transport-Security (on direct HTTPS or a trusted HTTPS proxy) are set on responses. Disable with securityHeaders: false.
TRACE method disabled by default: Eliminates Cross-Site Tracing attack surface. Re-enable for debugging via enableTrace: true (not recommended in production).
Deep frozen config: getConfigOptions() now freezes nested plain objects, not just the top-level copy.

Full service example

const bodyParser = require('body-parser')
const restana = require('restana')

const service = restana()
service.use(bodyParser.json())

const pets = // ...

service
  .get('/pets/:id', async (req, res) => {
    res.send(await pets.findOne(req.params.id))
  })
  .get('/pets', async (req, res) => {
    res.send(await pets.find())
  })
  .delete('/pets/:id', async (req, res) => {
    res.send(await pets.destroy(req.params.id))
  })
  .post('/pets/:name/:age', async (req, res) => {
    res.send(await pets.create(req.params))
  })
  .patch('/pets/:id', async (req, res) => {
    res.send(await pets.update(req.params.id, req.body))
  })

service.start(3000)

API and features

Supported HTTP methods:

const methods = ['get', 'delete', 'put', 'patch', 'post', 'head', 'options']

⚠️ TRACE is disabled by default in v6.0.0 to reduce attack surface (Cross-Site Tracing risk). Re-enable explicitly for debugging with enableTrace: true in the service constructor:
const service = restana({ enableTrace: true })
service.trace('/debug', (req, res) => res.send('Echo: ' + req.url))

Using .all routes registration

You can also register a route handler for all supported HTTP methods:

service.all('/allmethodsroute', (req, res) => {
  res.send(200)
})

Starting the service

service.start(3000).then((server) => {})

Stopping the service

service.close().then(()=> {})

Accessing configuration options

const opts = service.getConfigOptions()

getConfigOptions() returns an isolated configuration snapshot. Plain objects and arrays are recursively cloned and frozen, preventing third-party middleware from modifying internal framework options. The server and other custom class instances remain live references and should not contain secrets.

Async / Await support

service.post('/star/:username', async (req, res) => {
  await starService.star(req.params.username)
  const stars = await starService.count(req.params.username)

  res.send({ stars })
})

Sending custom headers

res.send('Hello World', 200, {
  'x-response-time': 100,
  vary: ['accept', 'origin']
})

⚠️ Security-sensitive and hop-by-hop headers are blocked from the headers parameter for security reasons: transfer-encoding, content-length, connection, keep-alive, host, set-cookie. Use res.setHeader() explicitly if you need to set these.

The "res.send" method

Same as in express, for restana we have implemented a handy send method that extends every res object.

Supported datatypes are:

null
undefined
String
Buffer
Object
Stream (errors on the stream are handled gracefully, terminating the response instead of leaving the connection hanging)
Promise (recursive promise resolution is capped at a depth of 3 to prevent event loop starvation)

Boolean payloads are serialized as JSON. A number passed as the first argument remains the shorthand for an HTTP status code.

Example usage:

service.get('/promise', (req, res) => {
  res.send(Promise.resolve('I am a Promise object!'))
})

The send method signature

res.send(
  // data payload
  'Hello World', 
  // response code (default 200)
  200, 
  // optional response headers (default NULL)
  {
    'x-cache-timeout': '5 minutes'
  }, 
  // optional res.end callback
  err => { /*...*/ }
)

Optionally, you can also just send a response code:
res.send(401)

Global error handling

By default, restana returns a generic Internal Server Error message to the client, preventing internal details from being leaked. The HTTP status code is preserved from err.status, err.code, or err.statusCode (defaults to 500).

To customize error responses, provide your own errorHandler:

const service = require('restana')({
  errorHandler (err, req, res) {
    console.log(`Something was wrong: ${err.message || err}`)
    res.send(err)
  }
})

service.get('/throw', (req, res) => {
  throw new Error('Upps!')
})

Note: res.send(err) masks the error's message and data by default. Set debugErrors: true only for local development when detailed responses are required. Production mode always masks details.

errorHandler not being called?

Issue: #81

Some middlewares don't call return next() inside a synchronous flow. In restana we enable async errors handling by default, however this mechanism fails when a subsequent middleware is just calling next() inside a sync or async flow.

Known incompatible middlewares:

body-parser (https://www.npmjs.com/package/body-parser)

How to bring async chain compatibility to existing middlewares? The body-parser example:

const jsonParser = require('body-parser').json()
const service = require('restana')()

service.use((req, res, next) => {
  return new Promise(resolve => {
    jsonParser(req, res, (err) => {
      return resolve(next(err))
    })
  })
})

Middlewares

Global middlewares

const service = require('restana')()

service.use((req, res, next) => {
  // do something
  return next()
});
...

Prefix middlewares

const service = require('restana')()

service.use('/admin', (req, res, next) => {
  // do something
  return next()
});
...

Route level middlewares

Connecting middlewares to specific routes is also supported:

const service = require('restana')()

service.get('/admin', (req, res, next) => {
  // do something
  return next()
}, (req, res) => {
  res.send('admin data')
});
...

As well, multiple middleware callbacks are supported:

const service = require('restana')()

const cb0 = (req, res, next) => {
  // do something
  return next()
}

const cb1 = (req, res, next) => {
  // do something
  return next()
}

service.get('/test/:id', [cb0, cb1], (req, res) => {
  res.send({ id: req.params.id })
})

Async middlewares

Since version v3.3.x, you can also use async middlewares as described below:

service.use(async (req, res, next) => {
  await next()
  console.log('All middlewares and route handler executed!')
}))
service.use(logging())
service.use(jwt())
...

In the same way you can also capture uncaught exceptions inside the request processing flow:

service.use(async (req, res, next) => {
  try {
    await next()
  } catch (err) {
    console.log('upps, something just happened')
    res.send(err)
  }
})
service.use(logging())
service.use(jwt())

Nested routers

Nested routers are supported as well:

const service = require('restana')()
const nestedRouter = service.newRouter()

nestedRouter.get('/hello', (req, res) => {
  res.send('Hello World!')
})
service.use('/v1', nestedRouter) 
...

In this example the router routes will be available under /v1 prefix. For example: GET /v1/hello

Third party middlewares support:

All middlewares using the function (req, res, next) signature format are compatible with restana.

Examples :

raw-body: https://www.npmjs.com/package/raw-body. See demo: raw-body.js
express-jwt: https://www.npmjs.com/package/express-jwt. See demo: express-jwt.js
body-parser: https://www.npmjs.com/package/body-parser. See demo: body-parser.js

Service Events

Service events are accessible through the service.events object, an instance of https://nodejs.org/api/events.html

Available events

service.events.BEFORE_ROUTE_REGISTER: This event is triggered before registering a route.

AWS Serverless Integration

restana is compatible with the serverless-http library, so restana based services can also run as AWS lambdas 🚀

// required dependencies
const serverless = require('serverless-http')
const restana = require('restana')

// creating service
const service = restana()
service.get('/hello', (req, res) => {
  res.send('Hello World!')
})

// lambda integration
const handler = serverless(service)
module.exports.handler = async (event, context) => {
  return await handler(event, context)
}

See also:
Running restana service as a lambda using AWS SAM at https://github.com/jkyberneees/restana-serverless

Cloud Functions for Firebase Integration

restana restana based services can also run as Cloud Functions for Firebase 🚀

// required dependencies
const functions = require("firebase-functions");
const restana = require('restana')

// creating service
const service = restana()
service.get('/hello', (req, res) => {
  res.send('Hello World!')
})

// lambda integration
exports = module.exports = functions.https.onRequest(service.callback())

Serving static files

You can read more about serving static files with restana in this link: https://itnext.io/restana-static-serving-the-frontend-with-node-js-beyond-nginx-e45fdb2e49cb

Also, the restana-static project simplifies the serving of static files using restana and docker containers:

Swagger/OpenAPI integration

https://www.npmjs.com/package/restana-swagger-validator

Third party integrations

// ...
const service = restana()
service.get('/hello', (req, res) => {
  res.send('Hello World!')
})

// using "the callback integrator" middleware
const server = http.createServer(service.callback())
//...

Application Performance Monitoring (APM)

As a Node.js framework implementation based on the standard http module, restana benefits from out of the box instrumentation on existing APM agents such as:

Elastic APM - Routes Naming

"Routes Naming" discovery is not supported out of the box by the Elastic APM agent, therefore we have created our custom integration.

// getting the Elastic APM agent
const agent = require('elastic-apm-node').start({
  secretToken: process.env.APM_SECRET_TOKEN,
  serverUrl: process.env.APM_SERVER_URL
})

// creating a restana application
const service = require('restana')()

// getting restana APM routes naming plugin 
const apm = require('restana/libs/elastic-apm')
// attach route naming instrumentation before registering service routes
apm({ agent }).patch(service)

// register your routes or middlewares
service.get('/hello', (req, res) => {
  res.send('Hello World!')
})

// ...

New Relic - Routes Naming

"Routes Naming" discovery is not supported out of the box by the New Relic APM agent, therefore we have created our custom integration.

// getting the New Relic APM agent
const agent = require('newrelic')

// creating a restana application
const service = require('restana')()

// getting restana APM routes naming plugin 
const apm = require('restana/libs/newrelic-apm')
// attach route naming instrumentation before registering service routes
apm({ agent }).patch(service)

// register your routes or middlewares
service.get('/hello', (req, res) => {
  res.send('Hello World!')
})

// ...

Using this project? Let us know 🚀

https://goo.gl/forms/qlBwrf5raqfQwteH3

Breaking changes

6.1

Restana 6.1 improves lifecycle reliability, secure defaults, performance tooling, and TypeScript support.

Added:

trustProxy explicitly enables forwarded-protocol handling for HSTS.
debugErrors explicitly enables detailed local error responses.
TypeScript coverage for lifecycle, events, callback integration, and TRACE opt-in.
Reproducible installs and performance smoke checks in CI.

Changed:

start() now rejects on listen errors such as EADDRINUSE.
Error details are masked by default in every environment and remain masked in production.
Boolean response bodies are serialized as JSON; array-valued response headers are supported.
routerCacheSize: 0 now correctly disables route caching.
Configuration snapshots recursively clone and freeze arrays and support circular plain objects.
Forwarded protocol headers are ignored unless trustProxy: true is configured.
Connection-specific, proxy-authentication, upgrade, and cookie headers are blocked from the res.send() header map.

Removed:

The obsolete disableResponseEvent example and install-time survey.
Legacy Travis CI configuration and the broken low-level performance demo.

6.0

Restana version 6.0 focuses on security hardening and reducing attack surface.

Added:

Minimum Node.js version is now v24.x (current LTS).

Changed:

TRACE HTTP method is no longer supported by default. Removed from methods.js to prevent Cross-Site Tracing (XST) risks. Re-enable for debugging with { enableTrace: true } in the service constructor.
res.send(data, code, headers) now validates the headers parameter. Security-sensitive and hop-by-hop headers (transfer-encoding, content-length, connection, keep-alive, host, set-cookie) are silently dropped. Invalid header key characters (CRLF, newlines) are caught and skipped instead of crashing with a 500 error.
parseErr() now respects NODE_ENV. In production, res.send(err) masks err.message and strips err.data to prevent internal details from leaking. In other environments, behavior is unchanged.
getConfigOptions() now deep freezes nested plain objects in addition to the top-level freeze. The server reference is a live object and is excluded from freezing.
Default security headers are now set on every response: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0. Strict-Transport-Security is set automatically when TLS is detected (via req.socket.encrypted or x-forwarded-proto: https header). Disable with { securityHeaders: false }.
New securityHeaders option allows disabling default security headers entirely (default: true).

5.2

Restana version 5.2 includes important security hardening while remaining backward compatible for most users.

Changed:

The default errorHandler no longer sends err.message or err.data to clients. It now returns a generic { code, message: 'Internal Server Error' } response. If you need the previous behavior, provide a custom errorHandler.
getConfigOptions() now returns a frozen shallow copy of the options object instead of a direct mutable reference.
Stream responses (res.send(stream)) now handle stream errors gracefully, terminating the response instead of leaving the connection hanging.
Promise resolution in res.send() is now capped at a depth of 3 to prevent event loop starvation from deeply nested promise chains.

4.x

Restana version 4.x is much more simple to maintain, mature and faster!

Added:

Node.js v10.x+ is required.
0http sequential router is now the default and only HTTP router.
Overall middlewares support was improved.
Nested routers are now supported.
Improved error handler through async middlewares.
New getRouter and newRouter methods are added for accesing default and nested routers.

Removed:

The response event was removed.
find-my-way router is replaced by 0http sequential router.
Returning result inside async handler is not allowed anymore. Use res.send...

3.x

Removed:

Support for turbo-http library was dropped.

Media

restana = faster and efficient Node.js REST APIs: https://itnext.io/restana-faster-and-efficient-node-js-rest-apis-1ee5285ce66

Support / Donate 💚

You can support the maintenance of this project:

PayPal: https://www.paypal.me/kyberneees
TRON Wallet: TJ5Bbf9v4kpptnRsePXYDvnYcYrS5Tyxus

Uh oh!

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Introduction

Express.js comparison (in the eyes of ChatGPT/OpenAI)

Performance

Speed of Development

Features

Usage

Configuration options

Security defaults (v6.0+)

Full service example

API and features

Supported HTTP methods:

Using .all routes registration

Starting the service

Stopping the service

Accessing configuration options

Async / Await support

Sending custom headers

The "res.send" method

The send method signature

Global error handling

errorHandler not being called?

Middlewares

Global middlewares

Prefix middlewares

Route level middlewares

Async middlewares

Nested routers

Third party middlewares support:

Service Events

Available events

AWS Serverless Integration

Cloud Functions for Firebase Integration

Serving static files

Swagger/OpenAPI integration

Third party integrations

Application Performance Monitoring (APM)

Elastic APM - Routes Naming

New Relic - Routes Naming

Using this project? Let us know 🚀

Breaking changes

6.1

6.0

5.2

4.x

3.x

Media

Support / Donate 💚