Skip to content

Commit

Permalink
Introduce documentation (#222)
Browse files Browse the repository at this point in the history 
* Introduce documentation

* Update some docs

* Update some more docs
  • Loading branch information
@nikostoulas
nikostoulas authored Feb 8, 2021
1 parent 34f01ea commit 3cd9739
Show file tree
Hide file tree
Showing 28 changed files with 1,725 additions and 285 deletions.
257 changes: 3 additions & 254 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

# Orka

A node.js framework to quickly bootstrap new servers.
A modern Node.js framework based on koa@2 that comes powered with RabbitMQ, Kafka, MongoDB and Redis integrations out of the box.

## Installation

Expand All @@ -37,7 +37,7 @@ config = {
redis: {
url:'',
options: {
tls: { // If those fileds are empty they will not be passed in
tls: { // If those fields are empty they will not be passed in
ca: [], // Redis driver. This way you can have the same app working
cert: '',// with a redis that support tls and a redis that doesn't with
key: '' // environment variable changes only.
Expand Down Expand Up @@ -109,256 +109,5 @@ builder({…some static options here…})
.start(8080)
```

For detailed usage please see the examples.
For detailed usage please see the [documentation](https://workable.github.io/orka).

To run the examples:

- clone orka project
- npm install
- npm run build
- you should be ready to run one of the examples locally. E.g.:
`node examples/simple-example/app.js`

## Kafka
If you're going to use kafka from a MacOS, you'll need to add the following to your bash_profile/zshrc file
```
export LDFLAGS="-L/usr/local/opt/libiconv/lib"
export CPPFLAGS="-I/usr/local/opt/libiconv/include"
```

## Health Middleware
It supports a health middleware that currently checks the availablity of mongo
configuration and responds wheather the connectivity with the underlying database is stable. This is essential for liveness probes of several cloud providers such as K8s.

Example route configuration

```js
const { middlewares: { health } } = require('@workablehr/orka');

module.exports = {
get: {
'/health': health,
'/users': async (ctx, next) => {
ctx.body = await User.find();
}
}
};
```

## ValidateBody and ValidateQueryString Middlewares
It supports validation middlewares for both body or query string parameters
using the joi validation module. @hapi/joi is now a dependency of orka.

Example route configuration

```js
const { middlewares: { validateBody, validateQueryString } } = require('@workablehr/orka');

module.exports = {
get: {
'/users': [validateQueryString(SOME_SCHEMA), async (ctx, next) => {
// Do something
}]
},
post: {
'/users': [validateBody(SOME_SCHEMA), async (ctx, next) => {
// Do something
}]
},
};
```
## Metrics Middleware
It supports exporting custom application metrics that can be picked by *Prometheus*.
In order to use this middleware you should also enable the *prometheus plugin* described in the following section.

Example route configuration

```js
const { middlewares: { metrics } } = require('@workablehr/orka');

module.exports = {
get: {
'/metrics': metrics,
'/users': async (ctx, next) => {
ctx.body = await User.find();
}
}
};
```
## Prometheus metrics
Prometheus is optional. In order to enable it install the dependency first:

```sh
npm i prom-client
```
And add to your configuration

```js
{
prometheus:{
enabled: true
}
}
```

It can either be used in conjunction with the `metrics` middleware (pull mode) or if you wish to use it in a non web context, using the *PushGateway* via the provided `#push()` method.

The `#push()` method will fail with an error, unless you configure the push gateway url:

```js
{
prometheus:{
enabled: true,
gatewayUrl: 'http://your.push.gateway'
}
}
```

Bull is configured to export bull queue depth/failed metrics, so if you use Bull,
you should also enable Prometheus, otherwise you will receive some complaints in the
logs.

## Bull Queues
Bull is an optional dependency. Should you want to use it in your project with Orka, install it first
```
npm i bull
```
Bull uses `Redis` as a backend, in order to configure redis with bull, you have 2 options:
1. Reuse the connection properties of your existing redis configuration ( `config.redis...` )
2. Configure bull specific connection options like so:
```js
{
bull: {
redis: {
url: '',
tls: {
ca: '',
cert: '',
key: ''
}
}
}
}
```
To configure your application queues, use the following configuration:
```js
{
bull: {
queue: {
options: {
removeOnComplete: true // This is applied to all queues
},
queues: [
{
name: 'queue_one',
options: {}
},
{
name: 'queue_two',
options: { delay: 15000 } // This is applied to queue_two
}
]
}
}
}
```
The `options` in both cases can be any of [JobOptions](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/b4330da8ebd802197809ca6f349961a506679d3d/types/bull/index.d.ts#L369).

## Request Context
Orka by default exposes a Request Context to the app.

It can be used for setting/getting variables that can be accessible in every code file (within the request's life). It uses nodeJS `async_hooks` to store this information.

By default it appends `requestId` and `visitor` (if you have the option `config.visitor.orka` enabled) in the request context. The `requestId` is retrieved using the option `config.traceHeaderName`

### Log Tracer
If the Request Context is enabled, orka by default appends `requestId` and `visitor` to all the application logs automatically.


### Configuration
If you don't specify anything in your `config.requestContext` it defaults to:

```js
{
"requestContext": {
"enabled": true
"logKeys": ["requestId", "visitor"] // These are the keys that will be appended automatically to your logs
}
}
```

### getRequestContext
This method can be used to access the request context within your app.

Returns:
A Map<string, any> with the current request context

e.g.
```js
import {getRequestContext} from '@workablehr/orka'
```

### Examples
Using the request context on another file:

```js
// src/app.js
builder({...})
.useDefaults()
.start()

// src/services/a-service.js called after a HTTP call
import {getRequestContext, getLogger} from '@workablehr/orka'

export const method = async () => {
const ctx = getRequestContext();
const id = ctx.get('requestId');
// id = a-uid
getLogger('log').info('An informative log');
// Logs for json
// {
// "timestamp":"2020-11-18T19:38:14.810Z",
// "severity":"INFO",
// "categoryName":"log",
// "message":"An informative log",
// "context":{
// "requestId": "a-uid"
// }
// }
// Logs for console
// ["2020-11-18T19:38:14.810Z"] [INFO] [log] [a-uid] An informative log
};
```

Example of setting a variable in request context:

```js
// src/app.js
builder({...})
.useDefaults()
.start()

// src/config/routes.js
import {getRequestContext} from '@workablehr/orka'

module.exports = {
get: {
'/test': async (ctx, next) => {
await service.method();
},
},
prefix: {
'/foo': async (ctx, next) => {
getRequestContext().set('var', 'test');
await next();
}
}
};

// src/services/a-service.js called after a HTTP call
import {getRequestContext} from '@workablehr/orka'

export const method = async () => {
console.log(getRequestContext().get('var')); // prints test
};
```
46 changes: 46 additions & 0 deletions docs/_config.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
remote_theme: pmarsceill/just-the-docs
title: Orka
description: Orka is a modern Node.js framework based on koa@2 that comes powered with RabbitMQ, Kafka, MongoDB and Redis integrations out of the box
# Enable or disable the site search
# Supports true (default) or false
search_enabled: true

search:
# Split pages into sections that can be searched individually
# Supports 1 - 6, default: 2
heading_level: 2
# Maximum amount of previews per search result
# Default: 3
previews: 3
# Maximum amount of words to display before a matched word in the preview
# Default: 5
preview_words_before: 5
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 10
# Set the search token separator
# Default: /[\s\-/]+/
# Example: enable support for hyphenated search words
tokenizer_separator: /[\s/]+/
# Display the relative url in search results
# Supports true (default) or false
rel_url: true
# Enable or disable the search button that appears in the bottom right corner of every page
# Supports true or false (default)
button: false

aux_links:
"Orka on GitHub":
- "//github.com/Workable/orka"

# color_scheme: dark
heading_anchors: true
back_to_top: true
back_to_top_text: "Back to top"
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter

gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub"

baseurl: "/orka" # the subpath of your site, e.g. /blog
url: "https://workable.github.io" # the base hostname & protocol for your site, e.g. http://example.com
Loading

0 comments on commit 3cd9739

Please sign in to comment.