## 1. Project Overview & Quickstart (senecajs/seneca)

## File: README.md

![Logo][]
> A Node.js toolkit for Microservice architectures


|  | This open source module is sponsored and supported by [Voxgig](https://www.voxgig.com). |
|---|---|


# Seneca
[![Npm][BadgeNpm]][Npm]
[![NpmFigs][BadgeNpmFigs]][Npm]
[![Travis][BadgeTravis]][Travis]
[![Coveralls][BadgeCoveralls]][Coveralls]
[![DeepScan][BadgeDeepScan]][DeepScan]
[![CodeClimate][BadgeCodeClimate]][CodeClimate]
[![Gitter][BadgeGitter]][Gitter]

- __Lead Maintainer:__ [Richard Rodger][Lead]
- __Sponsor:__ [voxgig][Sponsor]

Seneca is a toolkit for writing microservices and organizing the
business logic of your app. You can break down your app into "stuff
that happens", rather than focusing on data models or managing
dependencies.

Seneca provides,

- __pattern matching:__ a wonderfully flexible way to handle business requirements

- __transport independence:__ how messages get to the right server is not something you
should have to worry about

- __maturity:__ 8 years in production (before we called it _microservices_), but was
once taken out by [lightning][]

- __plus:__ a deep and wide ecosystem of [plugins][]

- __book:__ a guide to designing microservice architectures: [taomicro][]

Use this module to define commands that work by taking in some JSON,
and, optionally, returning some JSON. The command to run is selected
by pattern-matching on the the input JSON. There are built-in and
optional sets of commands that help you build Minimum Viable Products:
data storage, user management, distributed logic, caching, logging,
etc. And you can define your own product by breaking it into a set of
commands - "stuff that happens".  That's pretty much it.

If you're using this module, and need help, you can:

- Post a [github issue][Issue],
- Tweet to [@senecajs][Tweet],
- Ask on the [Gitter][Gitter].

If you are new to Seneca in general, please take a look at [senecajs.org][Org]. We have
everything from tutorials to sample apps to help get you up and running quickly.

Seneca's source can be read in an annotated fashion by running `npm run annotate`. An
annotated version of each file will be generated in `./docs/`.

## Install
To install via npm,

```
npm install seneca
```

## Quick Example

```js
'use strict'

var Seneca = require('seneca')


// Functionality in seneca is composed into simple
// plugins that can be loaded into seneca instances.


function rejector () {
  this.add('cmd:run', (msg, done) => {
    return done(null, {tag: 'rejector'})
  })
}

function approver () {
  this.add('cmd:run', (msg, done) => {
    return done(null, {tag: 'approver'})
  })
}

function local () {
  this.add('cmd:run', function (msg, done) {
    this.prior(msg, (err, reply) => {
      return done(null, {tag: reply ? reply.tag : 'local'})
    })
  })
}


// Services can listen for messages using a variety of
// transports. In process and http are included by default.


Seneca()
  .use(approver)
  .listen({type: 'http', port: '8260', pin: 'cmd:*'})

Seneca()
  .use(rejector)
  .listen(8270)


// Load order is important, messages can be routed
// to other services or handled locally. Pins are
// basically filters over messages


function handler (err, reply) {
  console.log(err, reply)
}

Seneca()
  .use(local)
  .act('cmd:run', handler)

Seneca()
  .client({port: 8270, pin: 'cmd:run'})
  .client({port: 8260, pin: 'cmd:run'})
  .use(local)
  .act('cmd:run', handler)

Seneca()
  .client({port: 8260, pin: 'cmd:run'})
  .client({port: 8270, pin: 'cmd:run'})
  .use(local)
  .act('cmd:run', handler)


// Output
// null { tag: 'local' }
// null { tag: 'approver' }
// null { tag: 'rejector' }
```


## Running

To run normally, say in a container, use

```sh
$ node microservice.js
```

(where `microservice.js` is a script file that uses Seneca).
Logs are output in JSON format so you can send them to a logging service.

To run in test mode, with human-readable, full debug logs, use:

```
$ node microservice.js --seneca.test
```


## Why we built this?

So that it doesn't matter,

   * __who__ _provides_ the functionality,
   * __where__ it _lives_ (on the network),
   * __what__ it _depends_ on,
   * it's __easy__ to _define blocks of functionality_ (plugins!).

So long as _some_ command can handle a given JSON document, you're good.

Here's an example:

```javascript
var seneca = require('seneca')()

seneca.add({cmd: 'salestax'}, function (msg, done) {
  var rate  = 0.23
  var total = msg.net * (1 + rate)
  done(null, {total: total})
})

seneca.act({cmd: 'salestax', net: 100}, function (err, result) {
  console.log(result.total)
})
```

In this code, whenever seneca sees the pattern `{cmd:'salestax'}`, it executes the
function associated with this pattern, which calculates sales tax. There is nothing
special about the property `cmd` . It is simply the property we want to pattern match.
You could look for `foo` for all seneca cares! Yah!

The `seneca.add` method adds a new pattern, and the function to execute whenever that
pattern occurs.

The `seneca.act` method accepts an object, and runs the command, if any, that matches.

Where does the sales tax rate come from? Let's try it again:

```js
seneca.add({cmd: 'config'}, function (msg, done) {
  var config = {rate: 0.23}
  var value = config[msg.prop]
  done(null, {value: value})
})

seneca.add({cmd: 'salestax'}, function (msg, done) {
  seneca.act({cmd: 'config', prop: 'rate'}, function (err, result) {
    var rate  = parseFloat(result.value)
    var total = msg.net * (1 + rate)
    done(null, {total: total})
  })
})

seneca.act({cmd: 'salestax', net: 100}, function (err, result) {
  console.log(result.total)
})
```

The `config` command provides you with your configuration. This is cool because it
doesn't matter _where_ it gets the configuration from - hard-coded, file system,
database, network service, whatever. Did you have to define an abstraction API to make
this work? Nope.

There's a little but too much verbosity here, don't you think? Let's fix that:


```javascript
seneca.act('cmd:salestax,net:100', function (err, result) {
  console.log(result.total)
})
```

Instead of providing an object, you can provide a string using an
[abbreviated form][Jsonic] of JSON. In fact, you
can provide both:

```javascript
seneca.act('cmd:salestax', {net: 100}, function (err, result) {
  console.log(result.total)
})
```

This is a _very convenient way of combining a pattern and parameter data_.

### Programmer Anarchy

The way to build Node.js systems, is to build lots of little
processes. Here's a great talk explaining why you should do this:
[Programmer Anarchy](http://vimeo.com/43690647).

Seneca makes this really easy. Let's put configuration out on the
network into its own process:

```javascript
seneca.add({cmd: 'config'}, function (msg, done) {
  var config = {rate: 0.23}
  var value = config[msg.prop]
  done(null, { value: value })
})

seneca.listen()
```

The `listen` method starts a web server that listens for JSON
messages. When these arrive, they are submitted to the local Seneca
instance, and executed as actions in the normal way.  The result is
then returned to the client as the response to the HTTP
request. Seneca can also listen for actions via a message bus.

Your implementation of the configuration code _stays the same_.

The client code looks like this:


```javascript
seneca.add({cmd: 'salestax'}, function (msg, done) {
  seneca.act({cmd: 'config', prop: 'rate' }, function (err, result) {
    var rate  = parseFloat(result.value)
    var total = msg.net * (1 + rate)
    done(null, { total: total })
  })
})

seneca.client()

seneca.act('cmd:salestax,net:100', function (err, result) {
  console.log(result.total)
})
```

On the client-side, calling `seneca.client()` means that Seneca will
send any actions it cannot match locally out over the network. In this
case, the configuration server will match the `cmd:config` pattern and
return the configuration data.

Again, notice that your sales tax code _does not change_. It does not
need to know where the configuration comes from, who provides it, or
how.

You can do this with every command.

### Keeping the Business Happy

The thing about business requirements is that they have no respect for
common sense, logic or orderly structure. The real world is messy.

In our example, let's say some countries have single sales tax rate,
and others have a variable rate, which depends either on locality, or product category.

Here's the code. We'll rip out the configuration code for this example.

```javascript
// fixed rate
seneca.add({cmd: 'salestax'}, function (msg, done) {
  var rate  = 0.23
  var total = msg.net * (1 + rate)
  done(null, { total: total })
})


// local rates
seneca.add({cmd: 'salestax', country: 'US'}, function (msg, done) {
  var state = {
    'NY': 0.04,
    'CA': 0.0625
    // ...
  }
  var rate = state[msg.state]
  var total = msg.net * (1 + rate)
  done(null, {total: total})
})


// categories
seneca.add({ cmd: 'salestax', country: 'IE' }, function (msg, done) {
  var category = {
    'top': 0.23,
    'reduced': 0.135
    // ...
  }
  var rate = category[msg.category]
  var total = msg.net * (1 + rate)
  done(null, { total: total })
})


seneca.act('cmd:salestax,net:100,country:DE', function (err, result) {
  console.log('DE: ' + result.total)
})

seneca.act('cmd:salestax,net:100,country:US,state:NY', function (err, result) {
  console.log('US,NY: ' + result.total)
})

seneca.act('cmd:salestax,net:100,country:IE,category:reduced', function (err, result) {
  console.log('IE: ' + result.total)
})

```

In this case, you provide different implementations for different patterns. This lets you
isolate complexity into well-defined places. It also means you can deal with special
cases very easily.

## Contributing

The [Senecajs org][Org] encourages participation. If you feel you can help in any way, be
it with bug reporting, documentation, examples, extra testing, or new features feel free
to [create an issue][Issue], or better yet, [submit a Pull Request][Pull]. For more
information on contribution please see our [Contributing][Contrib] guide.


### Test
To run tests locally,

```
npm run test
```

To obtain a coverage report,

```
npm run coverage; open docs/coverage.html
```



## License
Copyright (c) 2010-2018 Richard Rodger and other contributors;
Licensed under __[MIT][Lic]__.



[BadgeCoveralls]: https://coveralls.io/repos/senecajs/seneca/badge.svg?branch=master&service=github
[BadgeDeepScan]: https://deepscan.io/api/teams/5016/projects/6816/branches/59148/badge/grade.svg
[BadgeCodeClimate]: https://api.codeclimate.com/v1/badges/3a95be9ab6432c620bea/maintainability
[BadgeNpm]: https://badge.fury.io/js/seneca.svg
[BadgeGitter]: https://badges.gitter.im/senecajs/seneca.svg
[BadgeNpmFigs]: https://img.shields.io/npm/dm/seneca.svg?maxAge=2592000
[BadgeTravis]: https://travis-ci.org/senecajs/seneca.svg?branch=master
[CoC]: http://senecajs.org/code-of-conduct
[Contrib]: http://senecajs.org/contribute
[Coveralls]: https://coveralls.io/github/senecajs/seneca?branch=master
[DeepScan]: https://deepscan.io/dashboard#view=project&tid=5016&pid=6816&bid=59148
[CodeClimate]: https://codeclimate.com/github/senecajs/seneca/maintainability
[Gitter]: https://gitter.im/senecajs/seneca
[Issue]: https://github.com/senecajs/seneca/issues/new
[Lead]: https://github.com/rjrodger
[Lic]: ./LICENSE
[Logo]: http://senecajs.org/files/assets/seneca-logo.jpg
[Npm]: https://www.npmjs.com/package/seneca
[Org]: http://senecajs.org/
[Pull]: https://github.com/senecajs/seneca/pulls
[Sponsor]: http://www.voxgig.com
[Travis]: https://travis-ci.org/senecajs/seneca?branch=master
[Tweet]: https://twitter.com/senecajs

[Jsonic]: https//github.com/rjrodger/jsonic
[Lightning]: http://aws.amazon.com/message/67457/
[Plugins]: https://github.com/search?utf8=%E2%9C%93&q=seneca&type=Repositories&ref=searchresults
[taomicro]: https://bitly.com/rrtaomicro

---

## File: docs/examples/write-a-plugin/README.md

How to Write a Seneca Plugin
============================

Example code from the [*How to Write A Plugin* article](http://senecajs.org/tutorials/how-to-write-a-plugin.html) on the [Seneca](http://senecajs.org) site.

---

## File: docs/create-a-release.md

# Creating a release

1.  Review github issues, triage, close and merge issues related to the release.
2.  Navigate to the [Org Test Rig][TestRig] and ensure all test are passing.
3.  Update CHANGES.md, with date release, notes, and version.
4.  Pull down the repository locally on the master branch.
5.  Ensure there are no outstanding commits and the branch is clean.
6.  Run `npm install` and ensure all dependencies correctly install.
7.  Run `npm run test` and ensure testing and linting passes.
8.  Run `npm version vx.x.x -m "version x.x.x"` where `x.x.x` is the version.
9.  Run `git push upstream master --tags`
10. Run `npm publish`
11. Run `npm tag seneca@VERSION next`
12. Run `npm tag seneca@VERSION plugin`
13. Go to the [Github release page][Releases] and hit 'Draft a new release'.
14. Paste the Changelog content for this release and add additional release notes.
15. Choose the tag version and a title matching the release and publish.
16. Notify core maintainers of the release via email.


[TestRig]: https://travis-ci.org/senecajs/seneca-test-rig
[Releases]: https://github.com/senecajs/seneca/releases

---

## File: docs/msg-transport-protocol.md

# Seneca message transport protocol

The protocol is a request/response model. However some requests do not
require responses, so the protocol also supports actor or pub/sub message flows.

The protocol is transport independent and simply assumes that JSON
documents can be delivered whole and as discrete individual documents.

The JSON document can contain any data. The property `meta$` is
reserved for Seneca meta data, but is not required. Seneca will
construct meta data with default values if `meta$` is not
present. This provides for the use case of simple manual HTTP
interactions with tools like `curl`.

The term _message_ refers to a single instance of an outbound request
JSON data transmitted between two specific service instances. The term
message does *not* refer to a message flow over multiple services, *nor*
to the optional JSON data response. The concept of the message
response should be considered subsumed within the concept of a
message, as a convenience of the protocol. If responses are to stand
in their own right as separate messages, then an asynchronous message
flow should be used.


# Request Document Meta Data

```js
{
  msg$:
  {
    vin:  // Transport protocol version increment
    sid:  // Seneca instance identifier of sender of this message
    out:  // fixed value of true,
    mid:  // Seneca message identifier, an opaque string,
    cid:  // Seneca correlation identifier, an opaque string,
    snc:  // true if synchronous (expecting response), false if asynchronous
    pat:  // pattern on the sending Seneca instance
    trk:  [ // array of previously visited seneca instances including timing,
      {
        sid: // Seneca instance identifier of sender (not always redundant!)
        mid: // Seneca message identifier of inbound message
        tms: [
          // local (sender instance) UTC milliseconds sent
        ]
      }
    ],
    rtn:  { // return path description
      urn: // full network address for http response, optional
    }
    ctm: { // custom data, use this for your own meta data, optional
      ...
    }
  }
}
```

## Notes

The full message identifier has the form _mid_/_cid_. The correlation
identifier is retained across service instances and action calls so
that the entire causal chain of a message flow can be traced.

The Seneca instance identifier is an opaque string. In debugging mode
it may be extremely short. By convention, as a debugging aid, and not
to be considered normative, the full instance identifier has internal
structure:

`12-random-chars-from-[0-9a-z]` / `UTC-absolute-milliseconds` / `network-address` / `local-process-number` / `user-tag` 

The `trk` array provides a history of the message flow through
services. When an inbound message causes further outbound messages,
the Seneca instance where the new outbound messages originate is added
to the tracking array. Each entry in `trk` represents exactly one
outbound request (the message), and at most one response.

The return path is a HTTP end point, by default, and is optional. The
`urn` is the full address of the end point, suitable for use in a HTTP
client. Transports may define additional return path meta data (for
example, response topic name on a message queue).

The `tms` array contains entries in UTC milliseconds, recording local
send and receive times. Seneca instances should complete these arrays
as much as possible. In particular, on receipt of responses, the final
receive time should always be added so that it is available to
plugins.


# Response Document Meta Data

This has the form:

```js
{
  meta$:
  {
    rid:  // Seneca instance identifier of sender of this response, not the sender of the request
    res:  // fixed value of true,
    mid:  // Seneca message identifier, as per inbound message
    cid:  // Seneca correlation identifier, as per inbound message
    trk:  [ // array of previously visited seneca instances including timing,
      {
        sid: // Seneca instance identifier of sender
        rid: // Seneca instance identifier of receiver
        mid: // Seneca message identifier of inbound message
        tms: [
          // local (sender instance) UTC milliseconds sent,
          // local (receiver instance) UTC milliseconds received
          // local (receiver instance) UTC milliseconds response sent
        ]
      }
    ],
    usr: { // user data, use this for your own meta data, optional
      ...
    }
  }
}
```

## Notes

The `trk` array includes as the last entry the Seneca instance that
finally acted on the message.

There may be multiple responses to a given outbound message. By
default only the first is provided to the response callback. to
receive all responses, use the `meta$: { multiple: true }` option when
submitting the message. The response callback will be called once for
each message, up to some limit in time or message volume.

The additional entries to the `tms` array can be used to measure local
processing time. Seneca does not assume remote clocks are synchronized
within some range; all times are locally valid only.


# Example Flows

Services: A, B

## A -> B; Synchronous

  * Raw message data: `{ a: 1 }`
  * Raw response data: `{ x: 1 }`

Request:

```js
{
  a: 1,
  meta$:
  {
    sid: 'A',
    act:  true,
    mid:  'm01',
    cid:  'c01',
    snc:  true,
    trk:  [ 
      {
        sid: 'A'
        mid: 'm01'
        tms: [ 1461023850000 ]
      }
    ],
    rtn:  {
      urn: 'http://192.168.0.1/rtn'
    }
  }
```

Response:

```js
{
  x: 1,
  meta$:
  {
    rid: 'B',  // NOTE: the Seneca id of the receiver
    res:  true,
    mid:  'm01',
    cid:  'c01',
    trk:  [ 
      {
        sid: 'A'
        rid: 'B',
        mid: 'm01'
        tms: [ 1461023850000, // time message sent
               1461023850200, // time message received
               1461023850250  // time response sent
             ]
      }
    ]
  }
```


## A -> B, C; Asynchronous

  * Raw message data: `{ a: 2 }`
  * No response.

Sent Request (at A):

```js
{
  a: 2,
  meta$:
  {
    sid: 'A',
    act:  true,
    mid:  'm02',
    cid:  'c02',
    snc:  false,
    trk:  [ 
      {
        sid: 'A',
        mid: 'm02'
        tms: [ 1461023851000 ]
      }
    ]
  }
```

Received Request (at B):

```js
{
  a: 2,
  meta$:
  {
    sid: 'A',
    act:  true,
    mid:  'm02',
    cid:  'c02',
    snc:  false,
    trk:  [ 
      {
        sid: 'A',
        rid: 'B',
        mid: 'm02'
        tms: [ 1461023851000,
               1461023851200,
             ]
      }
    ]
  }
```



## A -> B -> C; Chained synchronous

### A -> B; Synchronous

  * A raw message data: `{ a: 3 }`
  * B raw message data: `{ b: 1 }`
  * Waits for response from B -> C interaction
  * C raw response data: `{ y: 1 }`
  * B raw response data: `{ x: 2 }`
  * A is hosted on 192.168.0.1
  * B is hosted on 192.168.0.2

Request A -> B:

```js
{
  a: 3,
  meta$:
  {
    sid: 'A',
    act:  true,
    mid:  'm03',
    cid:  'c03',
    snc:  true,
    trk:  [ 
      {
        sid: 'A'
        mid: 'm03'
        tms: [ 1461023852000 ] // time sent by A
      }
    ],
    rtn:  {
      urn: 'http://192.168.0.1/rtn' // A
    }
  }
```

Request B -> C:

```js
{
  b: 1,
  meta$:
  {
    sid: 'B',  // NOTE: sending from B here
    act:  true,
    mid:  'm04', // NOTE: new message id
    cid:  'c03',  // NOTE: same as A -> B
    snc:  true,
    trk:  [ 
      {
        sid: 'A'
        rid: 'B',
        mid: 'm03'
        tms: [ 1461023852000,
               1461023852200, // time received by B
             ]
      },
      {
        sid: 'B'
        mid: 'm04'
        tms: [ 1461023852300 ] // time sent by B
      }
    ],
    rtn:  {
      urn: 'http://192.168.0.2/rtn' // B
    }
  }
```

Response to B -> C:

```js
{
  y: 1,
  meta$:
  {
    rid:  'C', // NOTE: responding from C
    res:  true,
    mid:  'm04',
    cid:  'c03',
    trk:  [ 
      {
        sid: 'A'
        rid: 'B',
        mid: 'm03'
        tms: [ 1461023852000,
               1461023852200,
             ]
      },
      {
        sid: 'B'
        rid: 'C',
        mid: 'm04'
        tms: [ 1461023852300,
               1461023852500, // time received by C
               1461023852600  // time sent from C
             ]
      }
    ]
  }
```


Response to A -> B:

```js
{
  y: 1,
  meta$:
  {
    rid:  'B', // NOTE: responding from B
    res:  true,
    mid:  'm03', // NOTE: back to working on m03 (presumably uses data from m04 response)
    cid:  'c03',
    trk:  [ 
      {
        sid: 'A'
        rid: 'B',
        mid: 'm03'
        tms: [ 1461023852000,
               1461023852200,
               1461023852800  // time m03 response sent by B
             ]
      },
      {
        sid: 'B'
        rid: 'C',
        mid: 'm04'
        tms: [ 1461023852300,
               1461023852500, 
               1461023852600,
               1461023852700, // time m04 response received by B
             ]
      }
    ]
  }
```

## 2. Official Technical Reference & Guides (senecajs/senecajs.github.io)

# senecajs.org
[![Build Status][travis-badge]][travis-url]
[![Gitter][gitter-badge]][gitter-url]

This repo contains the documentation website for [Seneca.js][]. These docs are available at
[senecajs.org][] or can be ran locally by cloning this repo and following the steps below.

## Run Locally
After cloning, you will need to get dependencies via npm,

```
npm install
```

Next simply build and serve to port `4000`,

```
npm run build
npm run docs
```

## Contributing
Seneca is an __open__ project and encourage participation. If you feel you can help in
any way, be it with examples, extra testing, tutorials, or new features please be our
guest.

Please make all content changes in the [/src/pages][] folder. All changes are built
just before we redeploy the site so you only need to include changes in your PR. Upon
your PR being accepted your changes will be deployed.


## License

Copyright (c) 2010 - 2017 Richard Rodger and other contributors. Licensed under [MIT][].

[/src/pages]: ./src/pages
[Seneca.js]: https://www.npmjs.com/package/seneca
[senecajs.org]: http://www.senecajs.org/
[Seneca]: http://senecajs.org

[travis-badge]: https://travis-ci.org/senecajs/senecajs.org.svg?branch=master
[travis-url]: https://travis-ci.org/senecajs/senecajs.org.svg?branch=master
[gitter-badge]: https://badges.gitter.im/Join%20Chat.svg
[gitter-url]: https://gitter.im/senecajs/seneca
[MIT]: ./LICENSE