StoneStoreBased (ssBased)

Overview

ssBased is a robust library developed by StoneStore to standardize the integration of various systems under a serverless architecture. It provides a unified wrapper for handling API interactions, logging, and monitoring, ensuring consistency and scalability across all StoneStore services.

This library is designed to simplify the development and maintenance of serverless applications by offering a structured approach to manage input, output, and monitoring within StoneStore's ecosystem.

Features

• Serverless Standardization:

  • Streamlined workflows for AWS Lambda functions and API Gateway integrations.
  • Simplified input/output handling with reusable components.

• Unified Logging:

  • Centralized logging structure using BaseLog.
  • Supports error, info, and performance logs with standardized formats.
  • Automatic Data Obfuscation: Protects sensitive information in logs automatically.

• Data Security & Privacy:

  • Automatic obfuscation of sensitive fields like authorization, access-token, cvv, card-number.
  • Configurable obfuscation via environment variables for custom sensitive fields.
  • Deep copy protection ensures original data remains unmodified.
  • Fail-safe mechanisms prevent logging system failures.

• Error Handling:

  • Custom error classes like CommandApiError for consistent exception management.
  • Type-safe responses for both success and failure cases.

• Monitoring and Observability:

  • Includes fields for observability, such as service ownership, environment details, and response times.
  • Ready-to-use hooks for integrating with monitoring tools.

Installation

npm install ssbased

Usage

Setting Up a Lambda Function

Here’s how you can use ssBased to handle input, process logic, and output responses in a Lambda function:

import { APIGatewayProxyHandler } from "aws-lambda";
import { CommandMapper } from "ssbased";
import { ExampleDomain } from "./domains/exampleDomain";

export const handler: APIGatewayProxyHandler = async (event, context) => {
  const domain = new ExampleDomain();

  const mapper = new CommandMapper(event, context, domain);
  return await mapper.execute();
};

Defining a Domain

Create a domain to encapsulate your business logic:

import { IDomain, IResponseApi } from "ssbased";

export class ExampleDomain implements IDomain {
  async execute(payload: Record<string, unknown>): Promise<IResponseApi> {
    return {
      statusCode: 200,
      body: JSON.stringify({ message: "Hello from StoneStore!" }),
    };
  }
}

Components

1. CommandMapper

The core handler for managing API Gateway events. It integrates with CommandApiInput and CommandApiOutput to ensure standardized workflows.

2. BaseLog

Centralized logging utility for structured logs. Includes project details, environment metadata, and custom fields like response times.

3. CommandApiInput

Processes incoming API Gateway requests, extracting parameters, headers, and payloads.

4. CommandApiOutput

Formats API responses for both success and error scenarios. Ensures consistent status codes and body structure.

Interfaces

IDomain

The contract for defining business logic.

interface IDomain {
  execute(
    payload: Record<string, unknown>,
    context: Context
  ): Promise<{
    statusCode: number;
    body: string;
  }>;
}

IResponseApi

Defines the structure of an API response.

interface IResponseApi {
  statusCode: number;
  body: string;
}

Error Handling

Use CommandApiError to handle exceptions consistently:

import { CommandApiError } from "ssbased";

throw new CommandApiError("Invalid Input", 400, "INVALID_INPUT", {
  detail: "The provided user ID is not valid.",
});

Monitoring and Observability

ssBased includes observability fields such as:

• Observability Owner: The team responsible for the service.
• Vertical: Business domain of the service.
• Environment: Deployment environment (e.g., dev, staging, prod).
• Response Time: Automatically calculated metrics for performance.

Data Obfuscation

ssBased automatically protects sensitive information in logs using intelligent obfuscation:

Default Protected Fields

The following fields are always obfuscated automatically:

• authorization / Authorization
• access-token / Access-Token
• cvv
• card-number

Custom Protected Fields

Add custom sensitive fields via environment variable:

# Add custom fields to obfuscate (comma-separated)
SSBASED_OBFUSCATE_FIELDS="password,secret,api-key,private-key,token"

Example: Before and After Obfuscation

Before (Original Data):

{
  "user": "john_doe",
  "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "payment": {
    "card-number": "4111-1111-1111-1111",
    "cvv": "123"
  }
}

After (Obfuscated Log):

{
  "user": "john_doe",
  "authorization": "**********CONFIDENCIAL**********",
  "payment": {
    "card-number": "**********CONFIDENCIAL**********",
    "cvv": "**********CONFIDENCIAL**********"
  }
}

Example Logs

{
  "observabilityOwner": "StoneStore Team",
  "observabilityVertical": "E-commerce",
  "ownerProject": "Product Service",
  "nodeVersion": "16.x",
  "serviceName": "product-service",
  "ssBasedVersion": "1.0.0",
  "timestamp": "2024-11-28T14:35:00.000Z",
  "environment": "production",
  "layer": "APPLICATION",
  "responseTime": 120,
  "httpInput": {
    "path": "/products",
    "method": "GET",
    "authorization": "**********CONFIDENCIAL**********"
  },
  "httpOutput": {
    "statusCode": 200,
    "body": "{"products":[]}"
  }
}

Contributing

We welcome contributions from the StoneStore team to improve ssBased. Please adhere to our internal contribution guidelines and submit your pull requests through the company’s repository.

License

ssBased is proprietary software developed by StoneStore. Unauthorized use or distribution is strictly prohibited. Contact the StoneStore team for inquiries regarding usage permissions.

Contact

For support or further information, reach out to the StoneStore Technology Team:

• Email: [email protected]
• Website: stonestore.co