Backk

[![version][version-badge]][package] [![Downloads][downloads]][package] [![MIT License][license-badge]][license]

<h1 align="center">Backk<br/></h1> <h2 align="center">Backends for Kubernetes</h2> <h2 align="center">A Node.js framework for creating security-first cloud-native microservices for Kubernetes in Typescript</h2> <h3 align="center">A task-oriented replacement for REST, GraphQL and RPC</h3>

Table of Contents

• Status
• Features
• Architecture
• How Backk Works?
• Prerequisites
• Get Started
• Example Backk Microservice
• Usage Documentation
• API Documentation
• Security Features
• OWASP TOP 10 Checklist
• Feedback
  • Report a Bug
  • Report a Security Vulnerability
  • Request a New Feature
  • Request a Documentation Improvement
  • Ask a Question
• Contributing
• Sponsor
• License

<a name="features"></a> Features

• Create synchronous and asynchronous microservices using
  • HTTP/1.1 or HTTP2
  • Apache Kafka
  • Redis
• Write your microservices using Typescript and plain functions that are called by remote clients
  • No need for learning any technology like REST, GraphQL or gRPC
  • Can be used both for resource and RPC style microservices
  • Optionally GraphQL syntax can be used to specify what fields are included in query responses
  • Backk does not really care if your microservice is really a microservice or more like a mini-service, macro-service or monolith.
• Supports subscription endpoints using Server Sent Events (SSE) in HTTP/1.1 and HTTP/2
• Supports different databases
  • PostgreSQL
  • MySQL
  • MongoDB
  • MariaDB
  • Vitess (MySQL compatible)
  • YugabyteDB (PostgreSQL compatible)
  • CockroachDB (PostgreSQL compatible)
• ORM (Object-relational mapper)
  • Entities
  • Comprehensive set of validations for all data types (number, string, Date, Arrays)
  • Drastically simplifies the definition of DTOs or totally removes the need for DTOs
• CLI for generating new Backk microservice projects
• Automatic database schema generation
• Recommended source code directory structure for creating uniform microservices
• Comprehensive set of NPM scripts from building and testing to Docker/Minikube/Helm management
• Easy access of remote Backk microservices
• Executing multiple service functions with one request
• Security
  • Builds distro-less non-root Docker images for the microservice
  • OAuth 2.0 Authorization support
  • Captcha verification support
  • Automatic password hashing using Argon2 algorithm
  • Automatic PII encryption/decryption
  • Mandatory validation using decorators is required for entity properties
    • e.g. string fields must have a maximum length validation and numbers must have minimum and maximum value validation
• Supports a response cache using Redis
• Distributed transactions with persistent sagas (This feature is coming soon)
• Automatic microservice documentation generation
  • TypeDoc
• Automatic microservice metadata/specification generation
  • OpenAPI v3
  • Backk custom format that contains additional info compared to OpenAPI v3 spec
• Metadata endpoints can be called to retrieve microservice metadata for dynamic clients
• Automatic microservice integration test generation for Postman and Newman
• Automatic client code generation for Kubernetes cluster internal and web frontend clients
• Built-in Observability
  • Distributed tracing using OpenTelemetry API (Jaeger)
  • Log file format conforming to Open Telemetry specification
  • Metrics collection using OpenTelemetry API (Prometheus)
• Startup functions which are executed once on microservice startup
• Scheduled functions
  • Scheduled as per client request
  • Cron jobs
• Built-in Kubernetes Liveness, Readiness and Startup probes support
• Ready-made Dockerfiles
• Ready-made Docker Compose file setting up an integration testing environment
• Ready-made Helm templates for Kubernetes deployment
• Ready-made CI pipelines (currently only Github workflow)

<a name="architecture"></a>Architecture

Backk microservices are cloud-native microservices running in a Kubernetes cluster. Microservices can run in one or more namespaces. One Backk microservice consists of service(s) which consist of service function(s). These services and their functions comprise the API of your microservice.

For example, if your have Backk microservice has service emailNotificationService and it has function sendEmail, that service function can be accessed with HTTP URL path emailNotificationService.sendEmail. If your Backk microservice is named notification-service and is installed in default Kubernetes namespace, you can access your service function over HTTP like this: https://<kube-cluster-edge-fqdn>/notification-service.default/emailNotificationService.sendEmail

<a name="howbackkworks"></a> How Backk Works?

Backk microservices are written using Node.js and Typescript. A Backk microservice consists of one or more services classes with their dedicated purpose. Each service class can contain one or more service functions (class methods) that implement the service functionality. Each service function can have zero or exactly one parameter of JavaScript Class type. Service function returns a value, which can be null, a JavaScript value that can be converted to JSON or error.

Synchronously, Backk microservice can be accessed via HTTP. By default, each service function in the Backk microservice is accessible via HTTP POST method. But it is possible to configure to access service functions via HTTP GET method.

Asynchronously, Backk microservices can be accessed via Kafka and/or Redis. In case of Kafka, Backk microservice reads messages from a topic named after the microservice and message key tells the service function to execute and message value is the argument for the service function. In case of Redis, Backk microservice uses a list named after the microservice and pops service function calls from the list.

It is possible to simultaneously access the Backk microservice both synchronously and asynchronously using any combinations of all the three communication methods: HTTP, Kafka and Redis

Let's have a short example to showcase accessing Backk microservice over HTTP.

Our microservice consist of one service SalesItemService that is for creating sales items and getting the created sales items, and it is using a MySQL database as a persistent data store.

Let's create the SalesItemService service interface in src/services/salesitem directory:

SalesItemService.ts

import { DefaultPostQueryOperationsImpl, Many, One, PromiseErrorOr, Service } from 'backk';
import SalesItem from './types/entities/SalesItem';

export interface SalesItemService extends Service {
  createSalesItem(salesItem: SalesItem): PromiseErrorOr<One<SalesItem>>;
  getSalesItems(postQueryOperations: DefaultPostQueryOperationsImpl): PromiseErrorOr<Many<SalesItem>>;
}

Let's create the SalesItem entity class in src/services/salesitem/types/entities directory:

SalesItem.ts

import { _Id, Entity, IsAscii, IsFloat, Length, MinMax, ReadWrite } from 'backk';

@Entity()
export default class SalesItem extends _Id {
  @IsAscii()
  @Length(1, 128)
  @ReadWrite()
  name!: string;
  
  @IsFloat()
  @MinMax(0, Number.MAX_VALUE)
  @ReadWrite()
  price!: number;
}

Let's create the service implementation class in src/services/salesitem directory:

SalesItemServiceImpl.ts

import { DataStore, DefaultPostQueryOperationsImpl, CrudEntityService, Many, One, PromiseErrorOr } from 'backk';
import { SalesItemService } from './SalesItemService';
import SalesItem from './types/entities/SalesItem';

export default class SalesItemServiceImpl extends CrudEntityService implements SalesItemService {
  constructor(dataStore: DataStore) {
    super({}, dataStore);
  }
  
  createSalesItem(salesItem: SalesItem): PromiseErrorOr<One<SalesItem>> {
    return this.dataStore.createEntity(SalesItem, salesItem);
  }
  
  getSalesItems(postQueryOperations: DefaultPostQueryOperationsImpl): PromiseErrorOr<Many<SalesItem>> {
    return this.dataStore.getAllEntities(SalesItem, postQueryOperations, false);
  }
}

Let's create the microservice implementation class in src directory and instantiate our sales item service:

microservice.ts

import { Microservice, MySqlDataStore } from 'backk';
import SalesItemServiceImpl from './services/salesitem/SalesItemServiceImpl'

const dataStore = new MySqlDataStore();

export default class MicroserviceImpl extends Microservice {
  private readonly salesItemService = new SalesItemServiceImpl(dataStore);
  // If you had other services in you microservice, you would instantiate them here

  constructor() {
    super(dataStore);
  }
}

const microservice = new MicroserviceImpl();
export default microservice;

Now we can create a new sales item with an HTTP POST request:

POST /salesItemService.createSalesItem
Content-Type: application/json

{
  "name": "Sales item 1",
  "price": 49.95
}

And we get a response containing the created sales item with _id assigned:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "metadata": {}
  "data": {
    "_i