Let's Explore ARK Core: Kernel & Services [Part 3]

This is Part 3 of 6 in the Let’s Explore ARK Core series which documents the development of the next major release of ARK Core, alongside some tips & tricks on how to get started with contributing and building your next idea today.

Introduction

In the Part 1 and Part 2 of this series, we gave a rough overview of how the Core infrastructure and application bootstrapping process was revamped. Today we’ll learn what services inside of Core are, why they were introduced and what their job is to keep Core running.

What is a service?

Why were services introduced?

Services aren’t actually all new in Core 3.0 but rather a rework of how certain plugins operated in Core 2.0. Core 2.0 had one major issue that was the result of the late container and plugin system introduction, it was so heavily fragmented to the point where required plugins for functionality like loggers existed. You would always be required to include those plugins when bundling Core instead of them being part of a single package that you require in your own packages and have everything ready.

How were services introduced?

In Core 3.0 we introduced a new package called 

core-kernel

core-container

core-logger

core-event-emitter

The 

core-kernel

Part of 

core-kernel

services

• Actions
• Cache
• Config
• Events
• Filesystem
• Log
• Mixins
• Queue
• Schedule
• Validation

Registering your own services

Registering your own services is as easy as can be and only takes a few lines of code due to the abstractions that come out of the box for package developers. Lets first have a look at the abstract ServiceProvider that comes with Core to reduce the necessary boilerplate for service registrations.

@injectable()
export abstract class ServiceProvider {
    /**
     * The application instance.
     */
    @inject(Identifiers.Application)
    protected readonly app: Kernel.Application;
    /**
     * The application instance.
     */
    private packageConfiguration: PackageConfiguration;
    /**
     * The loaded manifest.
     */
    private packageManifest: PackageManifest;
    /**
     * Register the service provider.
     */
    public abstract async register(): Promise<void>;
    /**
     * Boot the service provider.
     */
    public async boot(): Promise<void> {
        //
    }
    /**
     * Dispose the service provider.
     */
    public async dispose(): Promise<void> {
        //
    }
    /**
     * Get the manifest of the service provider.
     */
    public manifest(): PackageManifest {
        return this.packageManifest;
    }
    /**
     * Set the manifest of the service provider.
     */
    public setManifest(manifest: PackageManifest): void {
        this.packageManifest = manifest;
    }
    /**
     * Get the name of the service provider.
     */
    public name(): string | undefined {
        if (this.packageManifest) {
            return this.packageManifest.get("name");
        }
        return undefined;
    }
    /**
     * Get the version of the service provider.
     *
     * @returns {string}
     * @memberof ServiceProvider
     */
    public version(): string | undefined {
        if (this.packageManifest) {
            return this.packageManifest.get("version");
        }
        return undefined;
    }
    /**
     * Get the configuration of the service provider.
     */
    public config(): PackageConfiguration {
        return this.packageConfiguration;
    }
    /**
     * Set the configuration of the service provider.
     */
    public setConfig(config: PackageConfiguration): void {
        this.packageConfiguration = config;
    }
    /**
     * Get the configuration defaults of the service provider.
     */
    public configDefaults(): JsonObject {
        return {};
    }
    /**
     * Get the configuration schema of the service provider.
     */
    public configSchema(): object {
        return {};
    }
    /**
     * Get the dependencies of the service provider.
     */
    public dependencies(): Kernel.PackageDependency[] {
        return [];
    }
    /**
     * Enable the service provider when the given conditions are met.
     */
    public async enableWhen(): Promise<boolean> {
        return true;
    }
    /**
     * Disable the service provider when the given conditions are met.
     */
    public async disableWhen(): Promise<boolean> {
        return false;
    }
    /**
     * Determine if the package is required, which influences how bootstrapping errors are handled.
     */
    public async required(): Promise<boolean> {
        return false;
    }
}

• The abstract register method is called by the bootstrapper classes that are responsible for registering services. This method should only register things, as its name indicates, and not start anything like HTTP servers.
  
• The boot method is called by the bootstrapper classes that are responsible for booting services. This should act based on what happened in the register method, i.e. start an HTTP server.
  
• The dispose method is called by the bootstrapper classes that are responsible for disposing of services. This should act based on what happened in the boot method, i.e. stop an HTTP server.
  
• The manifest method grants access to the package.json of a package to gather information like name or version.
  
• The setManifest is called by the bootstrapper classes that are responsible for registering services. The package.json file of a package will be automatically loaded, parsed and finally stored through this method.
  
• The name method returns the contents of the name property inside the package.json file of a package.
  
• The version method returns the contents of the version property inside the package.json file of a package.
  
• The config method grants access to the configuration of a package after it has been validated and normalized.
  
• The setConfig method is called by the bootstrapper classes that are responsible for registering services. The configuration will be validated, normalized and finally stored through this method.
  
• The configDefaults method is called by the bootstrapper classes that are responsible for registering services. The return value of this method will be merged with the user-supplied configuration to ensure all values are available.
  
• The configSchema method is called by the bootstrapper classes that are responsible for registering services. This method has to return a  schema that will be used to validate and normalize the configuration.
  
• The dependencies method is called by the bootstrapper classes that are responsible for registering services. The return value of this method has to be an array of objects that contain information like names and version constraints.
  
• The enableWhen / disableWhen methods are called by the bootstrapper classes when a block is applied and are responsible for (de)registering services. These methods have to return a boolean value that determines when to enable or disable a service.
  
• The required method is called by the bootstrapper classes that are responsible for registering services. This method has to return a boolean value that determines whether or not a service is required. Required plugins receive stricter error handling and any errors during registration or booting result in process termination.

That’s the functionality a service provider comes with out of the box
but the only methods you’ll interact with in most cases are register, boot and dispose. Let us take a look at an example service provider to illustrate their use.

import { Providers } from "@arkecosystem/core-kernel";
import { Server } from "@hapi/hapi";

export class ServiceProvider extends Providers.ServiceProvider {
    public async register(): Promise<void> {
        this.app.bind<Server>("api").toConstantValue(new Server());
    }
    
    public async boot(): Promise<void> {
        await this.app.get<Server>("api").start();
    }

    public async dispose(): Promise<void> {
        await this.app.get<Server>("api").stop();
    }
}

• The register method binds a new instance of a hapi.js server to the container without starting it.
  
• The boot method retrieves the previously registered server from the container and calls the start method on it.
  
• The dispose method retrieves the previously registered server from the container and calls the stop method on it.

Benefits of new service provider lifecycle

The by far biggest benefit for package developers is that it is now possible to alter or extend other packages due to how the application bootstrapping now works. An example of this would be a plugin that adds new routes or plugins to the 

core-api

What’s next?

I Want To Help With Development

To learn more about the program please read our  blog post and to learn more about ARK Core and blockchain visit our .