kato-js v0.4.1

kato-js

A simple but powerful microservices framework for Node-js.

About

The Kato-js microservices toolkit provides an abstraction layer between microservices and the technologies used to support publish/subscribe, remote procedure call, and data storage responsibilities.

Microservices can focus on implementing business logic, and the details regarding how data is exchanged between applications, services and data stores can be configured externally as part of deployment.

This package is the core library supporting the framework, and provides the central Broker component responsible for connecting microservice modules to message exchange and data storage providers.

Install

Install from the NPM repository, or directly from GitLab:

npm install kato-js
npm install gitlab:arsnebula/kato-js

Kato-js uses features of ES2015 and requires Node.js LTS (Argon) or above with the --harmony flag. Node.js LTS is the standard for all Kato-js components. For more infomation, see Node.js Releases.

Getting Started

A Broker is the core of framework, and is responsible for mapping requests generated by microservice clients to providers that process the request. Every request is defined by two properties: the method represents the command or action to perform, and the uri identifies an endpoint address.

These two properties are combined with any parameters specific to the method definition, and route-specific provider options, and are passed to a provider with each routed request.

Although the Kato-js framework defines and encourages the use of a standardized set of methods for publish/subscribe, remote procedure call, and key/value storage, their use if completely optional. You are free to design your own custom domain language specific to your systems architecture.

// import the core library and create a broker
const Kato = require( 'kato-js' )
const broker = new Kato.Broker()

// providers can be simple functions that accept and
// process requests from microservices through the broker
const logProvider = ( method, uri, params, options ) => {
  if ( method === 'log' && options.enabled ) {
    console.log( params )
  }
}

// provider behavior can be customized with options
// specific to any route
const logOptions = {
  'enabled': true
}

// add routes to the broker to match request methods and endpoints
// to providers (with support for wildcards)
broker.routes.add( [ 'log' ], '*', logProvider, logOptions )

// microservices are passed the broker and make requests using
// the methods and uri's you define for your architecture
broker.request( 'log', 'log.debug', 'Hello world!' )

In the previous example, we define a custom log method, and create a route to map it to a custom logging provider. In this example, the uri is not important as the target is the local system console. Microservices that make a requests through the broker do not need to be concerned with how the request is ultimately delivered and processed, or where the target endpoint is executed.

Standard Methods and Providers

The core library includes three local providers:

• LocalStorage is a simple in-memory key/value store with support for dynamic buckets and secondary indexing on tags.
• LocalProcedure supports local procedure call between microservices attached to the same broker.
• LocalEvent supports publish and subscribe between microservices attached to the same broker.

Combined, these three providers implement a complete set of standard methods to support publish/subscribe, remote procedure call, and key/value data storage. By utilizing the standard methods in your own microservices you gain the benefit of being able to plug in a variety of reusable providers for popular databases and messaging systems.

The included local providers give developers a complete toolkit for developing microservices without being concerned about connectivity to external systems or databases.

// import the core library and create a broker
const Kato = require( '..' )
const broker = new Kato.Broker()

// create instances of local providers
const localStorage = new Kato.Providers.LocalStorage()
const localProcedure = new Kato.Providers.LocalProcedure()
const localEvent = new Kato.Providers.LocalEvent()

// wire up each set of methods to a provider
broker.routes.add( localStorage.methods, '*', localStorage )
broker.routes.add( localProcedure.methods, '*', localProcedure )
broker.routes.add( localEvent.methods, '*', localEvent )

// publish a procedure
broker.request( 'register', 'kato.utils.echo', ( ...params ) => {
  return Promise.resolve( params )
} )

// invoke a *remote* procedure and get a result
broker.request( 'invoke', 'kato.utils.echo', ['aParam1', 'aParam2'] ).then(
  ( result ) => {
    console.log( 'Echo:', result )
  },
  ( error ) => {
    console.log( error )
  }
)

// set a value in the datastore
broker.request( 'set', 'kato.session.cache', 'aKey', 'aValue', [ 'aTag' ] )

// read the value from the datastore
broker.request( 'get', 'kato.session.cache', 'aKey' ).then(
  ( item ) => {
    console.log( 'Cache:', item )
  },
  ( error ) => {
    console.log( error )
  }
)

If you clone this repository with Git, you can run the above sample code using npm run sample to see it live in action.

We have only provided a basic introduction to the complete set of standard methods. For more details on full set of standard methods, see the API Documentation

Debugging

To assist with debugging, this library uses the debug package. To isolate debugging for specific components, you can use the following filters:

export DEBUG=kato-js:*
export DEBUG=kato-js:broker
export DEBUG=kato-js:routes
export DEBUG=kato-js:providers:*
export DEBUG=kato-js:providers:local-storage
export DEBUG=kato-js:providers:local-event
export DEBUG=kato-js:providers:local-procedure

Community Contributions

Feedback is welcome and appreciated. Issues or enhancement requests can be submitted using the Issues List on GitLab. For code contributions, please see our Contributing Guide.

License

MIT - Copyright (c) 2016 Chris Beckett and Ars Nebula