search

tazama-lf / frms-coe-startup-lib

frms-coe-startup-lib
Apache License 2.0
2 stars 0 forks source link

coe-startup-lib documentation update #35

Closed Sandy-at-Tazama closed 2 months ago

Sandy-at-Tazama commented 5 months ago

User Story Statement

As a Tazama system developer I want a template for updating the frms-coe-startup-lib readme documentation; so that I know what to document; and so that the documentation is consistent and complete; and so that the system is as simple as possible to maintain and configure for an inexperienced user

As a Tazama product owner I want the coe-startup-lib readme.md updated to align to the template and guide provided below so that the documentation is consistent and complete; and so that the system is as simple as possible to maintain and configure for an inexperienced user

also update: https://github.com/frmscoe/frms-coe-startup-lib/issues/76

Justus-at-Tazama commented 2 months ago

Table of Contents

Overview

frms-coe-startup-lib is a library designed to facilitate the startup and configuration of microservices within the FRMS ecosystem. It provides abstractions and implementations for initializing services, handling message queues, and managing application lifecycle events. The library supports various messaging systems, including NATS and JetStream, allowing for flexible and scalable service deployment.

Key features:

Installation

To install the frms-coe-lib package, you can use npm. This library requires Node.js and npm to be installed on your system.

  1. Install via npm:

    npm install @frmscoe/frms-coe-startup-lib --registry=https://npm.pkg.github.com

The npm package is hosted on GitHub. Make sure you're authenticated with GitHub and have the necessary permissions to access the package (read:packages).

  1. Importing in your project:

Once installed, you can import the library in your project:

  import { StartupFactory } from '@frmscoe/frms-coe-startup-lib';

  1. Dependencies:

    Ensure that you have all required dependencies installed, including any specific versions of third-party packages mentioned in the package's peer dependencies.

  2. Environment Configuration:

    Set up your environment configuration using a .env file or environment variables. Refer to the library's configuration requirements for details on necessary environment variables.

Usage

The frms-coe-startup-lib library provides an abstraction for initializing and managing messaging services like NATS. It includes the StartupFactory and IStartupService interface for creating and managing services.

1. Initializing a Service

The StartupFactory class initializes either a NATS or JetStream service based on the configuration. It implements the IStartupService interface.

Example:

import { StartupFactory, IStartupService } from '@frmscoe/frms-coe-startup-lib';

const server: IStartupService = new StartupFactory();
server.init(async (req, handleResponse) => {
  console.log('Received request:', req);
  handleResponse({ status: 'ok' });
});

2. Handling Messages

The init method of the IStartupService interface sets up the service to listen for incoming messages. The onMessageFunction callback is called with each received message.

Example:

import { IStartupService } from '@frmscoe/frms-coe-startup-lib';

async function onMessage(req: unknown, handleResponse: (response: object) => void) {
  console.log('Received request:', req);
  handleResponse({ status: 'ok' });
}

const server: IStartupService = new StartupFactory();
server.init(onMessage);

3. Handling Responses

The handleResponse method sends a response back to the message broker (e.g., NATS).

Example:

import { IStartupService } from '@frmscoe/frms-coe-startup-lib';

async function onMessage(req: unknown, handleResponse: (response: object) => void) {
  console.log('Received request:', req);
  handleResponse({ status: 'ok' });
}

const server: IStartupService = new StartupFactory();
server.init(onMessage);

4. NATS Service

The NatsService class implements the IStartupService interface for interacting with a NATS server. It provides methods for subscribing to subjects and publishing messages.

Example:

import { NatsService, IStartupService } from '@frmscoe/frms-coe-startup-lib';

const natsService: IStartupService = new NatsService();
natsService.init(onMessage);

async function onMessage(req: unknown, handleResponse: (response: object) => void) {
  console.log('Received request:', req);
  handleResponse({ status: 'ok' });
}

Modules and Classes

  1. Startup Factory

    • Class: StartupFactory
    • Description: Manages the initialization and handling of different startup services, either Jetstream or NATS.
    • Methods:
      • init(onMessage: onMessageFunction, loggerService?: ILoggerService, parConsumerStreamNames?: string[], parProducerStreamName?: string): Promise<boolean>: Initializes the startup service.
      • initProducer(loggerService?: ILoggerService, parProducerStreamName?: string): Promise<boolean>: Initializes the producer stream.
      • handleResponse(response: object, subject?: string[]): Promise<void>: Handles responses from the startup service.

  2. NATS Service

    • Class: NatsService
    • Description: Manages the initialization and handling of NATS services, including subscribing and publishing messages.
    • Methods:
      • init(onMessage: onMessageFunction, loggerService?: ILoggerService, parConsumerStreamNames?: string[], parProducerStreamName?: string): Promise<boolean>: Initializes the NATS service.
      • initProducer(loggerService?: ILoggerService, parProducerStreamName?: string): Promise<boolean>: Initializes the producer stream for NATS.
      • handleResponse(response: object, subject?: string[]): Promise<void>: Handles responses and publishes them to the producer stream.
      • subscribe(subscription: Subscription, onMessage: onMessageFunction): Promise<void>: Subscribes to a NATS subject and processes incoming messages.

  3. Jetstream Service

    • Class: JetstreamService
    • Description: Manages the initialization and handling of Jetstream services, including creating streams and consumers.
    • Methods:
      • init(onMessage: onMessageFunction, loggerService?: ILoggerService): Promise<boolean>: Initializes the Jetstream service.
      • initProducer(loggerService?: ILoggerService): Promise<boolean>: Initializes the producer stream for Jetstream.
      • handleResponse(response: unknown, subject?: string[]): Promise<void>: Handles responses and publishes them to the producer stream.
      • createConsumer(functionName: string, jsm: JetStreamManager, consumerStreamName: string): Promise<void>: Creates a consumer for Jetstream.
      • createStream(jsm: JetStreamManager, streamName: string, subjectName?: string): Promise<void>: Creates a stream in Jetstream.
      • consume(js: JetStreamClient, onMessage: onMessageFunction, consumerStreamName: string, functionName: string): Promise<void>: Consumes messages from a Jetstream consumer.

  4. Interfaces

    • Interface: IStartupConfig

    • Properties:

      • startupType: 'nats' | 'jetstream': The type of service to start.
      • ackPolicy: 'None' | 'All' | 'Explicit' | 'NotSet': Acknowledgment policy.
      • producerStorage: string: Storage type for the producer.
      • producerStreamName: string: Name of the producer stream.
      • producerRetentionPolicy: string: Retention policy for the producer.
      • consumerStreamName: string: Name of the consumer stream.
      • serverUrl: string: URL of the server.
      • env: string: Environment.
      • functionName: string: Function name.
      • streamSubject: string: Stream subject.

    • Interface: IStartupService

    • Methods:

      • init(onMessage: onMessageFunction, loggerService?: ILoggerService, parConsumerStreamNames?: string[], parProducerStreamName?: string): Promise<boolean>: Initializes the startup service.
      • initProducer(loggerService?: ILoggerService, parProducerStreamName?: string): Promise<boolean>: Initializes the producer stream.
      • handleResponse(response: object, subject?: string[]): Promise<void>: Handles responses.

    • Interface: ILoggerService

    • Methods:

      • log(message: string): void: Logs a message.
      • warn(message: string): void: Logs a warning message.
      • error(message: string | Error): void: Logs an error message.

  5. Types

    1. onMessageFunction
    • Type: (reqObj: unknown, handleResponse: responseCallback) => Promise<void>
      • Description: Represents a function to handle incoming messages.
      • Parameters:
      • reqObj: unknown: The request object.
      • handleResponse: responseCallback: The callback to handle the response.
    1. responseCallback
    • Type: (response: object, subject: string[]) => Promise<void>
      • Description: Represents a callback function to handle responses.
      • Parameters:
      • response: object: The response object.
      • subject: string[]: The subject(s) to which the response should be sent.

Configuration

Environment Variables

The frms-coe-startup-lib library uses environment variables to configure the startup process and service connections. Key environment variables include:

Configuration Files

The library supports configuration through .env files or other configuration file formats. These files can be used to set environment variables and other settings.

Message Broker Configuration

The message broker (NATS or JetStream) configuration is determined by the STARTUP_TYPE and related environment variables. The configuration includes details such as server URL, stream names, and acknowledgment policies.

Logging Configuration

Logging can be configured using environment variables or configuration files. Options include:

Stream and Subject Configuration

The library can be configured to interact with specific streams and subjects in the message broker. These are specified using the PRODUCER_STREAM, CONSUMER_STREAM, and STREAM_SUBJECT environment variables.

Advanced Configuration

Advanced configuration options are available for fine-tuning the library's behavior. These options can be set through additional configuration files or by extending the library's classes and interfaces.

External Dependencies

1. nats

2. ioredis

3. dotenv

4. node:path

5. pino

6. pino-elasticsearch

7. @elastic/ecs-pino-format

8. @grpc/grpc-js

9. @grpc/proto-loader

10. protobufjs

11. uuid

Contributing

If you want to contribute to the frms-coe-lib, please clone the repository and submit a pull request to the dev branch.

License

This library is a component of the Tazama project. The Tazama project is licensed under the Apache 2.0 License.