lucid-services/serviser

[serviser-template](https://github.com/lucid-services/serviser-template) plugin should help you get running. It generates working project skeleton based on minimal user input.  

Here is basic project file system structure:

- `config/`
- `config/config.js`
    - service configuration
- `lib/`
- `lib/routes/`
    - by convention, not required
    - contents of the directory will be recursively loaded (by user-defined rules) at service startup therefore filenames don't have to match any pattern.
- `lib/routes/v1.0/`
- `lib/routes/v1.0/<app_name>/`
- `lib/app.js`
    - by convention registers individual applications running within the service and exports the {@link AppManager} instance
    - A service can have multiple applications running on different ports.
- `logs/`
    - when logging into the fs
- `index.js`
    - is REQUIRED to export the {@link Service} instance


A service can be run by `npm start` or by `./node_modules/.bin/serviser run` command respectively.  
See {@tutorial 2.CLI-interface} for list of options.  

A {@link Service} instance holds the main representation of a running web service. It's aware of {@link AppManager} with {@link App Apps} which each may listen on different TCP port. Also the service object has access to essential {@link ResourceManager} & {@link RemoteServiceManager} & [Service Config](https://github.com/lucid-services/serviser-config)  

`require('serviser')` === {@link Service Service Constructor}  

### $PROJECT_ROOT/index.js
--------------------------

`index.js` is the entry point of a service and the only file with enforced purpose/structure. It's required to:  
* export {@link Service} instance object
* register external resources (database connections, dependent services etc..) needed by the service
* it's responsible for attaching {@link  Service#event:set-up} event listener which should initialize individual applications running within the service
* if any optional plugins are desirable, they should be loaded at bottom of the file by simply requiring (`require('serviser-<pluginname>')`) the package.


example:  

```javascript

const config  = require('serviser-config');
const Service = require('serviser').Service;

const service     = module.exports = new Service(config);

service.on('set-up', function() {
    //1.initialize service - do any synchronous/asynchrounous work to
    //                       be able to initize individual applications
    //2.initialize applications with route definitions
    require('./lib/app.js');
});

// serviser plugin registration
require('serviser-doc');
```

See {@link Service#event:set-up} event API.  


### $PROJECT_ROOT/lib/app.js
----------------------------
the destination and filename is purely conventional matter and can be placed in custom location.  
It initializes all {@link AppInterface applications} which will be run within the service.

```javascript

const moduleLoader = require('serviser').moduleLoader;
const service      = require('../index.js');

module.exports = service.appManager;

//creates a http application
service.buildApp('app-name', {
    //additional constructor options
    //see App class constructor API
}).once('post-init', function() {
    //custom initialization stuff
    //eg. add application wide middleware
});

//recursively `require`s `*.js` modules
moduleLoader.loadModules([
    __dirname + '/routes/v1.0/', //versioned endpoints
], {
    except: [] //list of paths that should NOT be imported
});
```

See the API of {@link App} class.
See {@tutorial 1b.Routing} tutorial for a basic endpoint definition.