Nutritious Pumpkin Meal

    oompa

    0.7.3 • Public • Published

    oompa

    A tiny pick-me-app for websocket-based, stateless, microservices.

    Installation

    Server (Node 6+) require('oompa')

    Client (Node 4+) require('oompa/client')

    Usage

    Server

    The oompa library draws inspiration from redux in that it handles typed tasks (called actions in redux).

    The task types are defined in an object called Application Schema.

    The Application Schema

    This is an example schema that defines the ADD task, giving it a factory method.

    const appSchema = {
      // The factory method accepts the task payload as a parameter,
      // and should return a promise
      ADD: ({x, y}) => Promise.resolve(+ y)
    };

    The healthcheck

    Every microservice should have a way to express health via HTTP (or so AWS says). This is why the second parameter of the server's constructor should be a method that returns a promise that is resolved when we know all is well, and rejected otherwise.

    Server methods

    • listen(port) - Start listening @port. Return a promise resolved when the server is ready.
    • close() - Close both HTTP and WebSockets servers, returns a promise resolved when both are closed.
    • use(middleware) - see middleware section below.

    Server events

    • error(Error err): emitted when the healthcheck fails with error err.
    • connection(Connection con): emitted when con is connected to the server.
    • terminated(Connection con): emitted when con is disconnected from the server.
    • reply(Reply r): emitted when a reply is ready to be sent. A reply has a type (OK|ERR) an id correlating to its request and payload or error.
    • stale(Reply): emitted after the reply event, when finding no live connection to reply to.

    An actual example

    const serverApp = {
      ADD: ({x, y}) => Promise.resolve(+ y), 
      SUB: ({x, y}) => Promise.resolve(- y), 
      MUL: ({x, y}) => Promise.resolve(* y), 
      DIV: ({x, y}) => Promise[? 'resolve' : 'reject'](/ y), 
    };
     
    function healthcheck() {
      return Promise.resolve(); // let's assume sunshine and rainbows
    }
     
    const server = new Server(serverApp, healthcheck);
     
    server
      .on('connection',
          () => logger.info('Connection created'))
      .on('terminated',
          () => logger.info('Connection terminated'))
      .on('error',
          err => logger.error(err, 'Server error'))
      .on('reply',
          ({type, id}) => logger.debug(`[${type}] for request #${id}`))
      .on('stale',
          ({type, id}) => logger.warn(`[${type}] for stale request #${id}`))
      .listen(PORT).then(() => logger.info(`Listening on port ${PORT}`));

    Client

    The Oompa client is actually very lean. You can use it in one of two forms:

    Lean usage

    const OompaClient = require('oompa/client');
    const client = new OompaClient('ws://localhost:9000');
     
    // dispatch accepts the type and the payload of the task
    client.dispatch('ADD', { x: 1, y: 6 }).then(result => {
      console.log(`${res} should be 7`);
    });

    Verbose Usage

    const OompaClient = require('oompa/client');
    const clientMethods = {
      // [methodName]: {type: [taskType], factory: [methodParams -> taskPayload]}
      add: { type: 'ADD', factory: (x, y) => ({x, y}) },
      sub: { type: 'SUB', factory: (x, y) => ({x, y}) },
      mul: { type: 'MUL', factory: (x, y) => ({x, y}) },
      div: { type: 'DIV', factory: (x, y) => ({x, y}) },
    };
    const client = new OompaClient('ws://localhost:9000', clientMethods);
     
    client.add(1, 2).then(...);

    Client methods

    • constructor(url, methods, options) - Create a new client with server @ url, the specified methods, with the following options:
      • noServer:false don't actually try to attempt to connect on init.
      • reconnectInterval:1000 try to reconnect to a server after server CLOSE event every reconnectInterval ms.
      • timeout:10000 disregard an attempt of request as a timeout after timeout ms.
      • attempts:3 reject a request after attempts timeouts as a timeout error.
      • tolerance:{ratio: 0.05, interval: 10000} attempt reconnect to server if after interval ms, the ratio of timeouts out of total requests exceeds ratio.
    • ping(timeout) - Check for the server's health. Wait for timeout ms until auto-rejecting.

    Client events

    • error: emitted by propagation from the underlying socket
    • host-closed: emitted when the host is closed abnormally (attempts to reconnect every 1 second)
    • reconnect-failed: emitted when an attempt to reconnect has failed
    • reconnected: emitted when the last attempt to reconnect was successful
    • OK:<TASK-ID>: emitted when task received an OK reply from the server, with its payload
    • ERR:<TASK-ID>: emitted when task received an ERR reply from the server, with its error

    Middleware

    Normally, a server simply forwards the request payload to its factory. Sometimes, however, you'd rather the request go through other steps before reaching the factory, if at all!

    const Server = require('oompa');
     
    const cache = new Map();
    function cacheMiddleware(request, next) {
      const type = request.type;
      const {x, y} = request.payload;
      const cacheUrl = `${type}/${x}/${y}`;
      if (cache.has(cacheUrl)) return cache.get(cacheUrl);
      return next(request).then(result => {
        cache.set(cacheUrl, result);
        return result;
      });
    }
     
    const serverApp = {
      ADD: ({x, y}) => Promise.resolve(+ y), 
      SUB: ({x, y}) => Promise.resolve(- y), 
      MUL: ({x, y}) => Promise.resolve(* y), 
      DIV: ({x, y}) => Promise[? 'resolve' : 'reject'](/ y), 
    };
     
    function healthcheck() {
      return Promise.resolve(); // let's assume sunshine and rainbows
    }
     
    const server = new Server(serverApp, healthcheck);
    server.use(cacheMiddleware);
     
    server
      .on('connection',
          () => logger.info('Connection created'))
      .on('terminated',
          () => logger.info('Connection terminated'))
      .on('error',
          err => logger.error(err, 'Server error'))
      .on('reply',
          ({type, id}) => logger.debug(`[${type}] for request #${id}`))
      .on('stale',
          ({type, id}) => logger.warn(`[${type}] for stale request #${id}`))
      .listen(PORT).then(() => logger.info(`Listening on port ${PORT}`));

    Install

    npm i oompa

    DownloadsWeekly Downloads

    0

    Version

    0.7.3

    License

    MIT

    Last publish

    Collaborators

    • oakfang