Closed Sandy-at-Tazama closed 2 months ago
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:
To install the frms-coe-lib
package, you can use npm. This library requires Node.js and npm to be installed on your system.
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
).
Once installed, you can import the library in your project:
import { StartupFactory } from '@frmscoe/frms-coe-startup-lib';
Dependencies:
Ensure that you have all required dependencies installed, including any specific versions of third-party packages mentioned in the package's peer dependencies.
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.
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.
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' });
});
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);
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);
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' });
}
Startup Factory
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.NATS Service
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.Jetstream Service
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.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.Types
(reqObj: unknown, handleResponse: responseCallback) => Promise<void>
reqObj: unknown
: The request object.handleResponse: responseCallback
: The callback to handle the response.(response: object, subject: string[]) => Promise<void>
response: object
: The response object.subject: string[]
: The subject(s) to which the response should be sent.The frms-coe-startup-lib
library uses environment variables to configure the startup process and service connections. Key environment variables include:
STARTUP_TYPE
: Specifies the startup type (nats
or jetstream
).NODE_ENV
: The node environment (development
, production
, etc.).SERVER_URL
: The URL of the server (e.g., NATS server).FUNCTION_NAME
: The name of the function or service.PRODUCER_STREAM
: The name of the producer stream.CONSUMER_STREAM
: The name of the consumer stream.STREAM_SUBJECT
: The subject to subscribe to in the message broker.PRODUCER_RETENTION_POLICY
: Retention policy for the producer (Limits
, Interest
, Workqueue
).ACK_POLICY
: Acknowledgment policy for the message broker (All
, Explicit
).PRODUCER_STORAGE
: Storage type (File
or Memory
).The library supports configuration through .env
files or other configuration file formats. These files can be used to set environment variables and other settings.
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 can be configured using environment variables or configuration files. Options include:
info
, debug
, warn
).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 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.
import { connect, type NatsConnection, type Subscription } from 'nats';
import Redis, { type Cluster } from 'ioredis';
.env
file into process.env
.import { config as dotenv } from 'dotenv';
import path from 'node:path';
import { type DestinationStream, pino } from 'pino';
import pinoElastic, { type DestinationStream } from 'pino-elasticsearch';
import { ecsFormat } from '@elastic/ecs-pino-format';
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import protobuf from 'protobufjs';
import { v4 } from 'uuid';
If you want to contribute to the frms-coe-lib
, please clone the repository and submit a pull request to the dev
branch.
This library is a component of the Tazama project. The Tazama project is licensed under the Apache 2.0 License.
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