@idio/core v1.4.0

@idio/core

@idio/core is a Koa2-based web server with some pre-installed middleware which facilitates quick creation of a web server with the essential functionality, such as serving static files, compression, body parsing, etc. It also provides full JSDoc documentation of all options for completion in IDEs. Other components such as @idio/database, @idio/route and @idio/jsx allow to build more complex websites (to come).

yarn add -E @idio/core

Table Of Contents

• Table Of Contents
• API
• async core(middlewareConfig?: MiddlewareConfig, config?: Config): IdioCore
  • MiddlewareConfig
  • Config
  • IdioCore
• Middleware Configuration
  • Session
  • File Uploads
  • Cross-Site Request Forgery
  • Parse Body
  • Checking Auth
  • Logging
  • Compression
  • Static Files
  • CORS
  • Frontend
• Custom Middleware
• Router Set-up
• Copyright

API

The package is available by importing its default function:

import idioCore from '@idio/core'

async core(  middlewareConfig?: MiddlewareConfig,  config?: Config,): IdioCore

The @idio/core accepts 2 arguments which are the middleware configuration object and server configuration object. It is possible to start the server without any configuration, however it will do nothing, therefore it is important to add some middleware configuration.

MiddlewareConfig: Middleware configuration for the idio core server.

Config: Server configuration object.

The return type contains the URL, Application and Router instances, and the map of configured middleware, which could then be passed to the router.

import('@goa/koa').Application _goa.Application: An instance of the Koa application.

import('@goa/koa').Middleware _goa.Middleware: An async middleware function.

import('koa-router').Router koa-router.Router: An instance of the Koa router.

import('http').Server http.Server: An instance of the Node's Server class.

IdioCore: An object containing the url and references to the app, router and middleware.

To start the server, the async method needs to be called and passed the middleware and server configuration objects. For example, the following code will start a server which serves static files with enabled compression.

import idioCore from '@idio/core'

const Server = async () => {
  const { url } = await idioCore({
    logger: {
      use: true,
    },
    static: {
      use: true,
      root: 'example/static',
      mount: '/static',
    },
    compress: {
      use: true,
      config: {
        threshold: 1024,
      },
    },
  }, {
    port: 8080,
  })
  console.log('File available at: %s/static/test.txt', url)
}

File available at: http://localhost:8080/static/test.txt

Middleware Configuration

The middleware can be configured according to the MiddlewareConfig. @idio/core comes with some installed middleware as dependencies to speed up the process of creating a web server. Moreover, any custom middleware which is not part of the bundle can also be specified here (see Custom Middleware).

Each middleware accepts the following properties:

SessionOptions

SessionConfig: Configuration passed to koa-session.

MulterOptions

import('http').IncomingMessage http.IncomingMessage

import('fs').Stats fs.Stats

import('koa-multer').StorageEngine koa-multer.StorageEngine

import('koa-multer').File koa-multer.File

Limits: An object specifying the size limits.

MulterConfig

CSRFOptions

CSRFConfig

BodyparserOptions

import('koa').Context koa.Context

BodyparserConfig

CheckauthOptions

LoggerOptions

LoggerConfig

CompressOptions

CompressConfig

StaticOptions

import('http').ServerResponse http.ServerResponse

(res: ServerResponse, path: string, stats: Stats) => any SetHeaders

StaticConfig

For example, the below configuration will serve files from both the static directory of the project, and the React.js dependency. When NODE_ENV environment variable is set to production, files will be cached for 10 days.

import { join, dirname } from 'path'
import idioCore from '@idio/core'

const STATIC = join(__dirname, 'static')
const REACT = join(dirname(require.resolve('react')), 'umd')

const DAY = 1000 * 60 * 60 * 24

const Static = async () => {
  const { url } = await idioCore({
    static: {
      use: true,
      root: [STATIC, REACT],
      mount: '/scripts',
      maxage: process.env.NODE_ENV == 'production' ? 10 * DAY : 0,
    },
  }, { port: 5004 })
  return url
}

Static server started on http://localhost:5004

import('koa').Context koa.Context

CorsOptions

CorsConfig

FrontendOptions: Allows to serve front-end JS files and CSS as modules, including from node_modules folder.

FrontendConfig

Custom Middleware

When required to add any other middleware in the application not included in the @idio/core bundle, it can be done in several ways.

1. Passing the middleware function as part of the MiddlewareConfig. It will be automatically installed to be used by the Application. All middleware will be installed in order it is found in the MiddlewareConfig.

import idioCore from '@idio/core'

/** @typedef {import('koa').Middleware} Middleware */

const APIServer = async (port) => {
  const { url } = await idioCore({
    // 1. Add logging middleware.
    /** @type {Middleware} */
    async log(ctx, next) {
      await next()
      console.log(' --> API: %s %s %s', ctx.method, ctx.url, ctx.status)
    },
    // 2. Add always used error middleware.
    /** @type {Middleware} */
    async error(ctx, next) {
      try {
        await next()
      } catch (err) {
        ctx.status = 403
        ctx.body = err.message
      }
    },
    // 3. Add validation middleware.
    /** @type {Middleware} */
    async validateKey(ctx, next) {
      if (ctx.query.key !== 'app-secret')
        throw new Error('Wrong API key.')
      ctx.body = 'ok'
      await next()
    },
  }, { port })
  return url
}

export default APIServer

Started API server at: http://localhost:5005
 --> API: GET / 403
 --> API: GET /?key=app-secret 200

2. Passing a configuration object as part of the MiddlewareConfig that includes the middlewareConstructor property which will receive the reference to the app. Other properties such as conf and use will be used in the same way as when setting up bundled middleware: setting use to true will result in the middleware being used for every request, and the config will be passed to the constructor.

import rqt from 'rqt'
import idioCore from '@idio/core'
import APIServer from './api-server'

const ProxyServer = async (port) => {
  // 1. Start the API server.
  const API = await APIServer(5001)
  console.log('API server started at %s', API)

  // 2. Start a proxy server to the API.
  const { url } = await idioCore({
    /** @type {import('koa').Middleware} */
    async log(ctx, next) {
      await next()
      console.log(' --> Proxy: %s %s %s', ctx.method, ctx.url, ctx.status)
    },
    api: {
      use: true,
      async middlewareConstructor(app, config) {
        // e.g., read from a virtual network
        app.context.SECRET = await Promise.resolve('app-secret')

        /** @type {import('koa').Middleware} */
        const fn = async(ctx, next) => {
          const { path } = ctx
          const res = await rqt(`${config.API}${path}?key=${ctx.SECRET}`)
          ctx.body = res
          await next()
        }
        return fn
      },
      config: {
        API,
      },
    },
  }, { port })
  return url
}

API server started at http://localhost:5001
Proxy started at http://localhost:5002
 --> API: GET /?key=app-secret 200
 --> Proxy: GET / 200

Router Set-up

After the Application and Router instances are obtained after starting the server as the app and router properties of the returned object, the router can be configured to respond to custom paths. This can be done by assigning configured middleware from the map and standalone middleware, and calling the use method on the Application instance.

import idioCore from '@idio/core'

async function pre(ctx, next) {
  console.log('  <-- %s %s',
    ctx.request.method,
    ctx.request.path,
  )
  await next()
}

async function post(ctx, next) {
  console.log('  --> %s %s %s',
    ctx.request.method,
    ctx.request.path,
    ctx.response.status,
  )
  await next()
}

const Server = async () => {
  const path = '/test'
  const {
    url, router, app, middleware: { bodyparser },
  } = await idioCore({
    // 1. Configure the bodyparser without using it for each request.
    bodyparser: {
      config: {
        enableTypes: ['json'],
      },
    },
  }, { port: 5003 })

  // 2. Setup router with the bodyparser and path-specific middleware.
  router.post(path,
    pre,
    bodyparser,
    async (ctx, next) => {
      ctx.body = {
        ok: true,
        request: ctx.request.body,
      }
      await next()
    },
    post,
  )
  app.use(router.routes())
  return `${url}${path}`
}

Page available at: http://localhost:5003/test
  <-- POST /test
  --> POST /test 200

Copyright

Middleware icons and logo from Deco Dingbats NF font.

Middleware types descriptions by their respective authors.