README.md

Kaptan

All in one micro-service framework with minimum dependencies and simplistic design. Most suitable for distributed applications and applications that serve multiple endpoints. The main concept behind Kaptan framework is using services as parts to build application.

Documentation is generated by TypeDoc and it's available at GitHub Pages of this repository.

• Introduction
• Available Services
• Getting Started
  • Creating an application
  • Adding services to application
  • Starting application
  • Developing services
• Network
  • Using the service
  • Packets, handlers and filters
  • Sockets and addresses
• License

Available Services

Package	Repository	Description
kaptan-http	ibrahimduran/node-kaptan-http	Simple HTTP service with utilities.

Getting Started

You can install Kaptan framework and its services easily from NPM using your favorite tool.

$ npm install --save kaptan
# or
$ yarn add kaptan

TypeScript users don't need to install any package for type definitions, they're served in the main package.

Creating an application

First parameter of Kaptan.constructor is label for the application. Having a label prevents mess in logs when you have multiple instances of kaptan.

import { Kaptan } from 'kaptan';

const kaptan = new Kaptan('my-app');

Or feel free to extend Kaptan class:

import { Kaptan } from 'kaptan';

class MyApp extends Kaptan {
  constructor() {
    super();

    // (lines below are only visible to who believes in unicorns)
    // My secret code - start


    // My secret code - end
  }
}

const app = new MyApp();

Adding services to application

Services can be installed from NPM. You can use Kaptan.use method to add service and service options.

import { CustomService } from 'kaptan-foo-bar';

kaptan.use(CustomService, { XYZ: false });

Starting application

This will fire up application and create service instances.

kaptan.start()
  .then(() => console.log('Application started!'))
  .catch(err => console.error(err));

Developing Services

Services are created by extending Service class. Service constructor takes kaptan intance as first parameter and options object as second. Also kaptan, logger and options properties get set in extended Service constructor.

import { Service } from 'kaptan';

class MyService extends Service {
  constructor(kaptan, options) {
    super(kaptan, {
      XYZ: 'some_default_val',
      ...options
    });

    // theese are automatically set
    console.log(this.kaptan);
    console.log(this.options);
    console.log(this.logger);

    // service dependencies/injections
    const fooBar = kaptan.services.spawn('FooBar');
  }

  async start() {
  }

  async stop() {
  }
}

You can use kaptan.services.spawn method to access service instances.

Network

Kaptan framework comes with a built-in Network service to simplify networking. All features of network service is async/await - promise compatible. It currently supports three protocols for sending packets; Request/Response for sending request and receiving response synchronously (using promises) and Raw for sending data without waiting for response.

Informations below are just a brief description for understanding the concept. Don't forget to check documentation to get more information about classes or methods.

Using the service

Kaptan package exports Network namespace which contains Network service. So you'll need to add Network.Network as service.

import { Network } from 'kaptan';

kaptan.use(Network.Network, { PORT: 5000 });

Packets, packet handlers and packet filters

Network.Packet is basically a data holder class with serialization logic in it. Network.PacketHandler instances can be passed to sockets and network service itself. By default, every one of packet handlers run when a packet arrives to the local socket but you can add filters to the handler using the Network.PacketFilter class.

Also you can use literal objects to create PacketHandler and PacketFilter instances in order simplify usage.

const filter = Network.PacketFilter.from({ ref: 'myPacket' });

const handler = new Network.PacketHandler({
    filter: filter,
    onParsed(socket, packet) {
    }
    
    onReceive(socket, raw) {
    }
});

Sockets and addresses

Network.Address is a common class that contains IP address utilities. Network.Socket is a wrapper for net's socket object. You can pass packet handlers to sockets as mentioned above. There are two main methods in socket; wait(filter) and send(packet). Since wait method returns a promise, you can create synchronized communications between server and client with power of async/await syntax of ES2017.

const filter = new Network.PacketFilter()
    .require('message');
    
const response = await socket.wait(filter);
socket.send({ data: { message: response.data.message } }); // mirror message

More about network will be available here soon..

License

MIT