Skip to content

Docs: Awos

Jump to bottom
ng-druid edited this page Aug 8, 2025 · 1 revision

Documentation for Awos Angular Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • AWS OpenSearch Integration
    • CRUD Operations with Signed URL
    • Rule-based Queries
  5. Core Components
    • AwosModule
  6. Key Factories
    • opensearchEntityCrudAdaptorPluginFactory
    • opensearchTemplateCrudAdaptorPluginFactory
    • createSignedHttpRequest
  7. Usage
    • Registering the Plugin
    • Performing CRUD Operations on OpenSearch
    • Querying Data in OpenSearch
  8. API Reference
  9. Examples
  10. Testing

1. Introduction

The Awos library provides seamless integration between Angular applications and AWS OpenSearch. It enables secure CRUD operations on OpenSearch entities and supports dynamic, rule-based queries using json-rules-engine. The library utilizes AWS Signature V4 for signed HTTP requests, ensuring secure interactions.

2. Installation

Install the library and necessary dependencies:

npm install awos @aws-sdk/client-opensearch @rollthecloudinc/crud @rollthecloudinc/auth @rollthecloudinc/awcog @rollthecloudinc/dparam

3. Overview

Awos combines the power of AWS OpenSearch with Angular, enabling developers to perform secure operations like create, update, delete, and query on OpenSearch entities. Key features include:

  • Integration with AWS Cognito for user authentication.
  • Generation of signed URLs using AWS Signature V4 for secure requests.
  • Rule-based and parameterized queries for flexible data retrieval from OpenSearch.

Features:

  • CRUD Operations: Supports CRUD operations on OpenSearch documents and templates.
  • Rule-based Queries: Enables complex filtering using json-rules-engine.
  • Secure Signed URLs: Leverages AWS Signature V4 for authenticated requests to OpenSearch.
  • Dependency Injection: Provides reusable factories and services for OpenSearch integration.

4. Key Concepts

4.1 AWS OpenSearch Integration

The library generates signed HTTP requests to interact securely with AWS OpenSearch endpoints. It supports both entity-based operations and template queries.

4.2 CRUD Operations with Signed URL

CRUD operations (create, update, delete, query) are securely executed using AWS signed requests. These ensure that interactions with OpenSearch are authenticated and authorized.

4.3 Rule-based Queries

Leverage json-rules-engine to perform filtering or conditional fetching of OpenSearch documents. Dynamic rules can be applied to structure flexible template queries.

5. Core Components

AwosModule

The AwosModule is the primary module for library integration. It registers plugins that enable CRUD operations using OpenSearch templates or entities. Dependencies such as AuthFacade and ParamEvaluatorService ensure smooth authentication and parameter resolution.

Example Usage:

import { AwosModule } from 'awos';

@NgModule({
  imports: [AwosModule],
  declarations: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

6. Key Factories

opensearchEntityCrudAdaptorPluginFactory

Creates an adaptor plugin capable of handling CRUD operations on OpenSearch entities. All operations (create, update, delete, query) rely on AWS signed requests for security.

Features:

  • Entity-based operations: Direct interaction with OpenSearch documents.
  • Parameterized options: Allows flexible configurations like domain, region, pipeline, and index.
  • Query execution: Supports retrieval of documents using rule-based logic.

opensearchTemplateCrudAdaptorPluginFactory

Creates an adaptor plugin for executing OpenSearch template-based queries with custom parameters and rules.

Features:

  • Template-based queries: Fetch results using OpenSearch templates.
  • Rule evaluations: Dynamic query conditions can be applied via json-rules-engine.
  • Secure execution: All operations are authenticated using signed HTTP requests.

createSignedHttpRequest

This utility generates signed HTTP requests for interactions with OpenSearch by leveraging AWS Signature V4. The signed URL ensures that only authenticated and authorized clients can make requests.

Parameters:

  • body: Request payload.
  • headers: Custom headers for the request.
  • hostname: OpenSearch domain hostname.
  • method: HTTP method.
  • path: REST API path to target OpenSearch resources.
  • protocol: Request protocol (http, https).
  • service: AWS service identifier (es for OpenSearch).
  • authFacade: Used for authentication via Cognito tokens.
  • cognitoSettings: AWS Cognito settings.

7. Usage

7.1 Registering the Plugin

To use the OpenSearch plugins (aws_opensearch_entity, aws_opensearch_template), import the AwosModule and configure AWS Cognito settings.

Example:

import { AwosModule } from 'awos';
import { CognitoSettings, COGNITO_SETTINGS } from '@rollthecloudinc/awcog';

const cognitoSettings: CognitoSettings = {
  identityPoolId: 'us-east-1:xxxxxx',
  region: 'us-east-1',
  userPoolId: 'us-east-1_xxxxxx',
};

@NgModule({
  imports: [AwosModule],
  providers: [{ provide: COGNITO_SETTINGS, useValue: cognitoSettings }],
})
export class AppModule {}

7.2 Performing CRUD Operations on OpenSearch

Create

Write a document to OpenSearch securely using the create method.

Example:

const crudInput = {
  object: { id: '123', name: 'New Document' },
  params: { domain: 'opensearch-domain', region: 'us-east-1', index: 'myIndex' },
  identity: () => of({ identity: 'document123' }),
};

opensearchEntityCrudAdaptorPluginFactory(authFacade, cognitoSettings, paramEvaluatorService, httpClient)
  .create(crudInput)
  .subscribe((response) => console.log('Create successful:', response.success));
Update

Modify an existing OpenSearch document using the update method.

Example:

const crudInput = {
  object: { id: '123', name: 'Updated Document' },
  params: { domain: 'opensearch-domain', region: 'us-east-1', index: 'myIndex' },
  identity: () => of({ identity: 'document123' }),
};

opensearchEntityCrudAdaptorPluginFactory(authFacade, cognitoSettings, paramEvaluatorService, httpClient)
  .update(crudInput)
  .subscribe((response) => console.log('Update successful:', response.success));
Query

Retrieve OpenSearch documents using rule-based filtering.

Example:

const queryInput = {
  params: { domain: 'opensearch-domain', region: 'us-east-1', index: 'myIndex' },
  rule: {
    conditions: {
      all: [
        { fact: 'identity', operator: 'startsWith', value: 'doc' },
      ],
    },
    event: { type: 'visible' },
  },
};

opensearchEntityCrudAdaptorPluginFactory(authFacade, cognitoSettings, paramEvaluatorService, httpClient)
  .query(queryInput)
  .subscribe((response) => console.log('Queried entities:', response.entities));

Template Query

Fetch data using OpenSearch templates.

Example:

const templateQueryInput = {
  params: { domain: 'opensearch-domain', region: 'us-east-1', index: 'my-template-index' },
  rule: {
    event: { type: 'visible' },
    conditions: { all: [{ fact: 'searchTerm', operator: 'term', value: 'example' }] },
  },
};

opensearchTemplateCrudAdaptorPluginFactory(platformId, authFacade, cognitoSettings, paramEvaluatorService, httpClient)
  .query(templateQueryInput)
  .subscribe((response) => console.log('Template query result:', response.entities));

8. API Reference

Factories

  1. opensearchEntityCrudAdaptorPluginFactory

    • create(input: CrudOperationInput): Observable<CrudOperationResponse>
    • update(input: CrudOperationInput): Observable<CrudOperationResponse>
    • query(input: CrudCollectionOperationInput): Observable<CrudCollectionOperationResponse>

  2. opensearchTemplateCrudAdaptorPluginFactory

    • query(input: CrudCollectionOperationInput): Observable<CrudCollectionOperationResponse>

  3. createSignedHttpRequest(params: CreateSignHttpRequestParams): Observable<HttpRequest>

    • Generates AWS Signature V4 signed HTTP requests.

9. Examples

Querying OpenSearch Entities

const input = {
  params: { domain: 'search-domain', region: 'us-west-2', index: 'products' },
  rule: {
    conditions: {
      all: [
        { fact: 'identity', operator: 'startsWith', value: 'prod' },
      ],
    },
    event: { type: 'visible' },
  },
};

opensearchEntityCrudAdaptorPluginFactory(...dependencies)
  .query(input)
  .subscribe((response) => console.log('Queried results:', response.entities));

10. Testing

Testing Entity Query Operations

describe('opensearchEntityCrudAdaptorPluginFactory', () => {
  it('should query OpenSearch entities based on rules', () => {
    const input = {
      params: { domain: 'test-domain', region: 'us-east-1', index: 'test-index' },
      rule: {
        conditions: { all: [{ fact: 'identity', operator: 'startsWith', value: 'test' }] },
        event: { type: 'visible' },
      },
    };

    opensearchEntityCrudAdaptorPluginFactory(...dependencies)
      .query(input)
      .subscribe((response) => expect(response.entities.length).toBeGreaterThan(0));
  });
});

Conclusion

The Awos Angular library enables secure interaction with AWS OpenSearch using authenticated signed URLs. It provides robust support for CRUD operations, parameterized template queries, and rule-based filtering. Whether you're managing documents or performing advanced searches, Awos delivers reliable tools for modern SaaS applications.

For questions, feature requests, or contributions, reach out!

Clone this wiki locally