Skip to content

Commit

Permalink
#461: updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
basmasking committed Feb 1, 2024
1 parent 0193459 commit 24988d8
Show file tree
Hide file tree
Showing 18 changed files with 67 additions and 67 deletions.
2 changes: 1 addition & 1 deletion documentation/docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ export default defineConfig({
{ text: 'Logging', link: '/monitor/logging' },
{ text: 'Health', link: '/monitor/health' },
{ text: 'Procedures', link: '/monitor/procedures' },
{ text: 'Nodes', link: '/monitor/nodes' }
{ text: 'Workers', link: '/monitor/workers' }
]
},
{
Expand Down
4 changes: 2 additions & 2 deletions documentation/docs/deploy/environments.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@ If you wonder why we've used 'standalone' instead of 'development' for the namin

Distributed applications require more of the infrastructure that comes with a cost. Therefore we like to keep things simple and try to use the standalone setup in production as long as possible. We recommend only using multiple Jitar services for availability and scalability reasons.

Setting up a distributed environment requires the same steps as a standalone setup. The only difference is that you need to create a configuration per service like the repository, gateway, and node(s). For the naming we use the service type, like we do with the standalone. Don't forget to add scripts to the `package.json` file.
Setting up a distributed environment requires the same steps as a standalone setup. The only difference is that you need to create a configuration per service like the repository, gateway, and worker(s). For the naming we use the service type, like we do with the standalone. Don't forget to add scripts to the `package.json` file.

If your environment requires multiple nodes, you can append a node name to the configuration. For example "node-sales", "node-orders", etc..
If your environment requires multiple workers, you can append a name to the configuration. For example "worker-sales", "worker-orders", etc..

## Other environments

Expand Down
8 changes: 4 additions & 4 deletions documentation/docs/deploy/health-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ next:

# Health checks

The [gateway service](../fundamentals/runtime-services#gateway) determines if a node still can be used safely by frequently checking its health. Health checks are used for health determination. Jitar has no out-of-the-box health checks, but you can create and add your own. A common use case is for checking database availability. In case a node can't access its database, we want the gateway to stop using it. Health checks can be added to any of the services.
The [gateway service](../fundamentals/runtime-services#gateway) determines if a worker still can be used safely by frequently checking its health. Health checks are used for health determination. Jitar has no out-of-the-box health checks, but you can create and add your own. A common use case is for checking database availability. In case a worker can't access its database, we want the gateway to stop using it. Health checks can be added to any of the services.

::: warning BREAKING CHANGES
Version 0.5 introduced breaking changes. Please check our [migration guide](https://github.com/MaskingTechnology/jitar/blob/main/migrations/migrate-from-0.4.x-to-0.5.0.md) for more information.
Expand Down Expand Up @@ -58,17 +58,17 @@ export default instance;
We can use this module file for the registration at the service:

```json
// services/node.json
// services/worker.json
{
"url": "http://localhost:3000",
"healthChecks": ["./databaseHealthCheck"],
"node":
"worker":
{
// ...
}
}
```

Once added, the node will trigger the check automatically. You can also check yourself using the health API. More information on this can be found in the [MONITOR section](../monitor/health).
Once added, the worker will trigger the check automatically. You can also check yourself using the health API. More information on this can be found in the [MONITOR section](../monitor/health).

**Note** that health checks are defined at the root level of the configuration. This means you can add health checks for all service types. When using external monitoring tools that monitor a cluster, this could be useful.
4 changes: 2 additions & 2 deletions documentation/docs/deploy/load-balancing.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ next:

Jitar has out-of-the-box load balancing support. It's provided by the [gateway service](../fundamentals/runtime-services#gateway), so that needs to be added to your environment in order to use it.

The load balancing system operates on function level. If a function is available on multiple nodes, the gateway will automatically balance the requests round robin over the nodes. The [function's fully qualified name (FQN)](../fundamentals/building-blocks#fully-qualified-name-fqn) is used to uniquely identify the functions.
The load balancing system operates on function level. If a function is available on multiple workers, the gateway will automatically balance the requests round robin over the workers. The [function's fully qualified name (FQN)](../fundamentals/building-blocks#fully-qualified-name-fqn) is used to uniquely identify the functions.

When a node registers itself at the gateway, the node will provide the FQNs of the functions it contains. The gateway creates a balancer per FQN and uses the next node per request. When a node contains FQNs that are already registered by the gateway, it will add the node to the balancer.
When a worker registers itself at the gateway, the worker will provide the FQNs of the functions it contains. The gateway creates a balancer per FQN and uses the next worker per request. When a worker contains FQNs that are already registered by the gateway, it will add the worker to the balancer.

6 changes: 3 additions & 3 deletions documentation/docs/deploy/segmentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,12 +82,12 @@ Imports have multiple properties that can be configured. These properties will b

### Trusted clients

When building a distributed application, you don't want all functions to be available by the outside world. Some functions are only used internally by other segments. To protect the access to these functions, Jitar provides a `trustKey` property in the [runtime services](../fundamentals/runtime-services#node). This key is used to create trusted clients. Trusted clients can access functions with the `protected` access level.
When building a distributed application, you don't want all functions to be available by the outside world. Some functions are only used internally by other segments. To protect the access to these functions, Jitar provides a `trustKey` property in the [runtime services](../fundamentals/runtime-services#worker). This key is used to create trusted clients. Trusted clients can access functions with the `protected` access level.

Any client that wants to access a protected function must provide a valid key. It needs to be added to the http header `X-Jitar-Trust-Key`. Any node that has a valid key is automatically considered a trusted client, and adds the access key to the http header of outgoing requests. Any node that doesn't have a valid access key is considered an untrusted client and can only access `public` functions.
Any client that wants to access a protected function must provide a valid key. It needs to be added to the http header `X-Jitar-Trust-Key`. Any worker that has a valid key is automatically considered a trusted client, and adds the access key to the http header of outgoing requests. Any worker that doesn't have a valid access key is considered an untrusted client and can only access `public` functions.

::: info Note
To enable trusted clients, the gateway must always have a trusted key configured. Any node that wants to register itself as a trusted client, must have the same value for the `trustKey` in its configuration.
To enable trusted clients, the gateway must always have a trusted key configured. Any worker that wants to register itself as a trusted client, must have the same value for the `trustKey` in its configuration.
:::

### Access protection
Expand Down
4 changes: 2 additions & 2 deletions documentation/docs/develop/application-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,8 @@ The `services` folder contains all [service configuration](../fundamentals/runti
```txt
services
├─ gateway.json
├─ node-account.json
├─ node-reporting.json
├─ worker-account.json
├─ worker-reporting.json
├─ proxy.json
├─ repository.json
└─ standalone.json
Expand Down
2 changes: 1 addition & 1 deletion documentation/docs/develop/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ next:

# Error handling

For handling errors the default JavaScript error system can be used for throwing and catching errors. When an error occurs it will be passed to the calling procedure until it’s catched like any normal JavaScript application. If the error occurs on a remote server, the error will be (de)serialized and rethrown on the calling node.
For handling errors the default JavaScript error system can be used for throwing and catching errors. When an error occurs it will be passed to the calling procedure until it’s caught like any normal JavaScript application. If the error occurs on a remote server, the error will be (de)serialized and thrown on the calling worker.

You can create your own custom errors and use the `instanceof` operator to distinguish them like this:

Expand Down
8 changes: 4 additions & 4 deletions documentation/docs/develop/middleware.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,19 +94,19 @@ export default instance;
We can use this module file for the registration at the service:

```json
// services/node.json
// services/worker.json
{
"url": "http://localhost:3000",
"node":
"worker":
{
"middlewares": ["./defaultRequestLogger"]
}
}
```

**Note** that middleware can only be added to a node, gateway, proxy and standalone service because they are actively involved with the communication system.
**Note** that middleware can only be added to a worker, gateway, proxy and standalone service because they are actively involved with the communication system.

It's likely that different services require different middleware. For example, you might want to add authentication middleware to the gateway and authorization middleware to the node.
It's likely that different services require different middleware. For example, you might want to add authentication middleware to the gateway and authorization middleware to the worker.

::: warning KEEP IN MIND
Middleware is executed in the order of registration. This means that the middleware that is added first is called first.
Expand Down
4 changes: 2 additions & 2 deletions documentation/docs/develop/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ The first endpoint is for requesting [assets](./assets). By default all files ar

Assets can be whitelisted per file, or by using glob patterns. For example the pattern `assets/**/*` whitelists all files and subfolder files in the assets folder.

The second endpoint is for requesting module files internally used by nodes to load their functions. Requesting a module file requires a valid client id provided by the repository at the registration of a node. The repository only allows requesting files with the .js extension that are placed in the application folder. To prevent any form of information leakage make sure the code does not contain sensitive information (like access keys).
The second endpoint is for requesting module files internally used by workers to load their functions. Requesting a module file requires a valid client id provided by the repository at the registration of a worker. The repository only allows requesting files with the .js extension that are placed in the application folder. To prevent any form of information leakage make sure the code does not contain sensitive information (like access keys).

::: tip PRO TIP
To prevent the access of server modules from any client, make sure that all modules are registered in a server [segment](../fundamentals/building-blocks#segments). The repository will provide a remote implementation if a client tries to load the module. Remote implementations do not contain any information other than function and parameter names.
Expand All @@ -57,7 +57,7 @@ export default class Authentication implements Middleware
}
```

In a distributed setup we register this middleware at the [gateway service](../fundamentals/runtime-services.md#gateway) to make sure a node only gets called when the user is authenticated. The authorization may depend on attributes gathered during the execution of the function. Therefore we add the authorization middleware to the [node service](../fundamentals/runtime-services#node).
In a distributed setup we register this middleware at the [gateway service](../fundamentals/runtime-services.md#gateway) to make sure a worker only gets called when the user is authenticated. The authorization may depend on attributes gathered during the execution of the function. Therefore we add the authorization middleware to the [worker service](../fundamentals/runtime-services#worker).

```ts
import { Middleware, Request, Response, NextHandler } from 'jitar';
Expand Down
4 changes: 2 additions & 2 deletions documentation/docs/examples/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ This example demonstrates how to distribute an application in production. It als

## Load balancing

Jitar comes with load balancing capabilities out-of-the-box. This example demonstrates how to load balance application segments by running them on multiple nodes.
Jitar comes with load balancing capabilities out-of-the-box. This example demonstrates how to load balance application segments by running them on multiple workers.

[View in repository](https://github.com/MaskingTechnology/jitar/tree/main/examples/concepts/load-balancing){target="_blank"}

Expand Down Expand Up @@ -64,7 +64,7 @@ This example demonstrates how to set up a node client. It’s for you when you a

## Health checks

For the health of a cluster it’s important that nodes can communicate their health status. In this example you’ll learn how to create heath checks and request the health of a service.
For the health of a cluster it’s important that workers can communicate their health status. In this example you’ll learn how to create heath checks and request the health of a service.

[View in repository](https://github.com/MaskingTechnology/jitar/tree/main/examples/concepts/health-checks){target="_blank"}

Expand Down
38 changes: 19 additions & 19 deletions documentation/docs/fundamentals/runtime-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,21 +100,21 @@ A full configuration example looks like this.

This is a core service that is always required, except when running Jitar as a [standalone service](#standalone).

## Node
## Worker

A node loads application segments and runs its functions on request.
A worker loads application segments and runs its functions on request.

### Segmentation

A node can load one or multiple segments, making it very easy to combine application pieces that have to be scaled yet. This strategy can save you a lot on hosting costs!
A worker can load one or multiple segments, making it very easy to combine application pieces that have to be scaled yet. This strategy can save you a lot on hosting costs!

::: warning KEEP IN MIND
Like any other service, a node runs on the server. Keep this in mind when creating and selecting the segments.
Like any other service, a worker runs on the server. Keep this in mind when creating and selecting the segments.
:::

### Gateway registration

When configured, a node can register itself to a [gateway service](#gateway) to become available in the cluster.
When configured, a worker can register itself to a [gateway service](#gateway) to become available in the cluster.

### Configuration properties

Expand All @@ -130,8 +130,8 @@ A full configuration example looks like this:

```json
{
"url": "http://node.example.com:3000",
"node":
"url": "http://worker.example.com:3000",
"worker":
{
"gateway": "http://gateway.example.com:3000",
"repository": "http://repository.example.com:3000",
Expand All @@ -148,19 +148,19 @@ This is a core service that is always required, except when running Jitar as a [

## Gateway

The gateway provides a single point of access for running remote application functions. It acts as a mediator between a client and multiple node services.
The gateway provides a single point of access for running remote application functions. It acts as a mediator between a client and multiple worker services.

### Routing

When a function request comes in, the gateway will look for a node containing the function and forwards the request.
When a function request comes in, the gateway will look for a worker containing the function and forwards the request.

### Load balancing

If a function is available on multiple nodes, the gateway will automatically balance the requests round robin over the nodes.
If a function is available on multiple workers, the gateway will automatically balance the requests round robin over the workers.

### Node monitoring
### Worker monitoring

The availability of nodes is actively monitored. If a node cannot be reached or replies to have [an unhealthy state](../monitor/health.md), it will be removed from the gateway.
The availability of workers is actively monitored. If a worker cannot be reached or replies to have [an unhealthy state](../monitor/health.md), it will be removed from the gateway.

### Caching

Expand All @@ -171,7 +171,7 @@ There aren't any caching options yet, but we are planning on implementing them.
The following configuration properties are available:

* repository - url of the repository (required).
* monitor - node monitoring interval in milliseconds (optional, default `5000`).
* monitor - worker monitoring interval in milliseconds (optional, default `5000`).
* middlewares - list of [middleware modules](../develop/middleware.md) to load (optional).
* trustKey - key for creating trusted clients (optional).

Expand All @@ -192,22 +192,22 @@ A full configuration example looks like this:

### When to use

This service is used for creating a cluster and is only useful when working with multiple nodes. It also works with a single node, but adds a lot of overhead.
This service is used for creating a cluster and is only useful when working with multiple workers. It also works with a single worker, but adds a lot of overhead.

## Proxy

The proxy acts as an intermediary between clients and a Jitar cluster. It's a single point of access for both the [repository](#repository) and [gateway](#gateway) / [node](#node) services.
The proxy acts as an intermediary between clients and a Jitar cluster. It's a single point of access for both the [repository](#repository) and [gateway](#gateway) / [worker](#worker) services.

### Request forwarding

The single purpose of the proxy is to forward requests to the right service. RPC requests are forwarded to the [gateway](#gateway) or [node](#node) service (depending on the configuration). Other requests are forwarded to the repository.
The single purpose of the proxy is to forward requests to the right service. RPC requests are forwarded to the [gateway](#gateway) or [worker](#worker) service (depending on the configuration). Other requests are forwarded to the repository.

### Configuration properties

The following configuration properties are available:

* gateway - url of the gateway (optional if node property set).
* node - url of the node (optional if gateway property set).
* gateway - url of the gateway (optional if worker property set).
* worker - url of the worker (optional if gateway property set).
* repository - url of the repository (required).
* middlewares - list of [middleware modules](../develop/middleware.md) to load (optional).

Expand All @@ -234,7 +234,7 @@ This service is not required, but very helpful for protecting your cluster. Comm

## Standalone

Combines the repository and node core services into a single instance.
Combines the repository and worker core services into a single instance.

### Configuration properties

Expand Down
Loading

0 comments on commit 24988d8

Please sign in to comment.