Runtime services

Jitar holds multiple types of services needed for orchestrating and executing distributed applications. Depending on your needs one or more Jitar instances can be used for running your application.

In this section you'll learn the available service types, what they do, when to use them and how to configure them.

Basic configuration

At the start of a Jitar instance, a configuration needs to be given telling the instance what service it needs to provide.

Configurations are placed in JSON files. The basic structure looks like this.

{
    "url": "SERVICE_URL",
    "setUp": ["SET_UP_SCRIPT"],
    "tearDown": ["TEAR_DOWN_SCRIPT"],
    "healthChecks": ["HEALTH_CHECK_SCRIPT"],
    "SERVICE_TYPE":
    {
        "PROPERTY_1": "…",
        "PROPERTY_2": "…"
    }
}

NOTE

The configuration also supports environment variables. They can be used by wrapping the variable name in ${}. For example, ${ENVIRONMENT_VARIABLE_1}.

{
    "PROPERTY_3": "${ENVIRONMENT_VARIABLE_3}"
}

There are four properties at root level:

• url - service url containing protocol, address and port (e.g. http://service.example.com:3000).
• setUp - optional list of set up scripts that gets executed on startup.
• tearDown - optional list of tear down scripts that gets executed on shutdown.
• healthChecks - optional list of health check scripts for checking the service health.
• SERVICE_TYPE - configuration of the specific service (differs per type).

An instance can only run one type of service. Each service has its own configuration properties. All types and their properties are explained next.

Repository

The repository holds and serves application files like a web server, with addition that it's segment aware.

File serving

The repository keeps track of every client and their segments. When a client requests a module file, the repository determines if it needs to serve the actual module or a remote implementation. It will only provide the actual module in case the module is unsegmented or gets requested from the same segment.

Besides serving modules to clients, it also serves application assets like images, documents, etc.. To protect the access to the application files, assets need to be whitelisted. This can be done per file, or by using glob patterns. For example the pattern assets/**/* whitelists all files and subfolder files in the assets folder.

Caching

All application files are served from a cache folder created by Jitar. This folder contains a copy of the application with additional generated files like segmentation information, remote module implementations and more. Detailed information can be found in the INTERNALS section.

Configuration properties

The following configuration properties are available:

• source - location of the application code (optional, default ./src).
• cache - location of the application cache (optional, default ./.jitar).
• index - file to serve when accessed by a web browser (optional, default index.html).
• serveIndexOnNotFound - when true, the index file will be served if the requested file is not found (default false).
• assets - list of whitelisted assets (optional, default undefined).
• overrides - map with import overrides (optional, default undefined).

A full configuration example looks like this.

{
    "url": "http://repository.example.com:3000",
    "repository":
    {
        "source": "./src",
        "cache": "./.jitar",
        "index": "index.html",
        "serveIndexOnNotFound": false,
        "assets": ["*.html", "*.js", "*.css", "assets/**/*"],
        "overrides": { "./my-module": "./alternative-module" }
    }
}

When to use

This is a core service that is always required, except when running Jitar as a standalone service.

Worker

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

Segmentation

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!

KEEP IN MIND

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 worker can register itself to a gateway service to become available in the cluster.

Configuration properties

The following configuration properties are available:

• gateway - url of the gateway (optional, in case no gateway is used).
• repository - url of the repository (required).
• segments - list of segment names to load (optional, loads all segments by default).
• middlewares - list of middleware modules to load (optional).
• trustKey - key for creating trusted client (optional).

A full configuration example looks like this:

{
    "url": "http://worker.example.com:3000",
    "worker":
    {
        "gateway": "http://gateway.example.com:3000",
        "repository": "http://repository.example.com:3000",
        "segments": ["segment1", "segment2"],
        "middlewares": ["./middleware1", "./middleware2"],
        "trustKey": "${MY_TRUST_KEY}"
    }
}

When to use

This is a core service that is always required, except when running Jitar as a standalone service.

Gateway

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 worker containing the function and forwards the request.

Load balancing

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

Worker monitoring

The availability of workers is actively monitored. If a worker cannot be reached or replies to have an unhealthy state, it will be removed from the gateway.

Caching

There aren't any caching options yet, but we are planning on implementing them. Please let us know if you need this, it will help us prioritize our work!

Configuration properties

The following configuration properties are available:

• repository - url of the repository (required).
• monitor - worker monitoring interval in milliseconds (optional, default 5000).
• middlewares - list of middleware modules to load (optional).
• trustKey - key for creating trusted clients (optional).

A full configuration example looks like this:

{
    "url": "http://gateway.example.com:3000",
    "gateway":
    {
        "repository": "http://repository.example.com:3000",
        "monitor": 5000,
        "middlewares": ["./middleware1", "./middleware2"],
        "trustKey": "${MY_TRUST_KEY}"
    }
}

When to use

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 and gateway / 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 or 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 worker property set).
• worker - url of the worker (optional if gateway property set).
• repository - url of the repository (required).
• middlewares - list of middleware modules to load (optional).

A full configuration example looks like this:

{
    "url": "http://proxy.example.com:3000",
    "proxy":
    {
        "gateway": "http://gateway.example.com:3000",
        "repository": "http://repository.example.com:3000",
        "middlewares": ["./middleware1", "./middleware2"]
    }
}

When to use

This service is not required, but very helpful for protecting your cluster. Common use cases are:

1. Entry point for web-browsers (prevents CORS)
2. Protect access to other services (in a DMZ)

Standalone

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

Configuration properties

The standalone service has the same configuration properties as the repository service:

• source - location of the application code (optional, default ./src).
• cache - location of the application cache (optional, default ./.jitar).
• index - file to serve when accessed by a web browser (optional, default index.html).
• serveIndexOnNotFound - when true, the index file will be served if the requested file is not found (default false).
• assets - list of whitelisted assets (optional, default undefined).
• middlewares - list of middleware modules to load (optional).
• overrides - map with import overrides (optional, default undefined).
• trustKey - key for creating trusted clients (optional).

A full configuration example looks like this:

{
    "url": "http://standalone.example.com:3000",
    "standalone":
    {
        "source": "./src",
        "cache": "./.jitar",
        "index": "index.html",
        "serveIndexOnNotFound": false,
        "assets": ["*.html", "*.js", "*.css", "assets/**/*"],
        "middlewares": ["./middleware1", "./middleware2"],
        "overrides": { "./my-module": "./alternative-module" },
        "trustKey": "${MY_TRUST_KEY}"
    }
}

When to use

This service is useful in both development and production environments. It's ideal for development because it only requires a single instance no matter the deployment requirements. In production it's the most simple deployment option for applications that do benefit from being distributed or replicated yet.