-
Notifications
You must be signed in to change notification settings - Fork 1
Docs: Aws3
- Introduction
- Installation
- Overview
-
Key Concepts
- AWS S3 Integration
- CRUD Operations with Signed URL
- Cognito Integration for Authentication
-
Core Components
Aws3Module
-
Key Factories
s3EntityCrudAdaptorPluginFactorycreateS3SignedHttpRequest
-
Usage
- Registering the Plugin
- Performing CRUD Operations
- Querying Data in S3
- API Reference
- Examples
- Testing
The AWS3 Angular library provides an efficient way to integrate AWS S3 into Angular applications. It leverages signed URLs for secure S3 object operations and integrates with AWS Cognito for identity management. The library works seamlessly with @rollthecloudinc/crud to provide CRUD operations on S3 objects and supports rule-based queries using json-rules-engine.
Install the library along with required dependencies:
npm install aws3 @aws-sdk/client-s3 @rollthecloudinc/crud @rollthecloudinc/awcog @rollthecloudinc/auth @rollthecloudinc/dparamAWS3 is designed for secure interaction with AWS S3 buckets using signed URL requests. It integrates with AWS Cognito for authentication, enabling authorized operations on S3 objects, such as create, read, update, delete, and query.
- Secure Object Operations: Uses pre-signed URLs with AWS Signature V4 for interacting with S3 objects.
- AWS Cognito Authentication: Governs access to resources via identity pool credentials.
- Dynamic CRUD Operations: Provides full CRUD functionality using S3 bucket storage for JSON objects.
-
Advanced Querying: Enables rule-based filtering and querying of S3 data using
json-rules-engine.
The library interacts with AWS S3 by generating signed HTTP requests using AWS Signature V4. These requests allow secure data exchanges without exposing AWS credentials.
CRUD operations (create, read, update, delete) are implemented using signed URLs, ensuring operations are performed securely and authenticated based on AWS credentials.
AWS Cognito is used to fetch temporary credentials for the user. It integrates seamlessly into the signed URL workflow, enforcing identity-based access control on S3 objects.
The Aws3Module is the entry point of the library. It registers the CRUD adaptor plugin (aws_s3_entity) and handles initialization of dependencies such as AuthFacade and ParamEvaluatorService.
Core Features:
- Automatic registration of S3 entity plugin for CRUD operations.
- Dependency injection for Cognito settings via
AWCOG. - Integration with
@rollthecloudinc/crudfor dynamic operations on S3 objects.
Example:
import { Aws3Module } from 'aws3';
@NgModule({
imports: [Aws3Module],
declarations: [],
exports: [],
})
export class AppModule {}This factory creates a CRUD adaptor plugin capable of interacting with AWS S3 objects using signed URLs. Its methods handle operations such as create, update, delete, and query.
Features:
- Secure Requests: Uses AWS Signature V4 for signing HTTP requests.
-
Dynamic Options: Supports parameters like
bucketandprefixfor flexible bucket configurations. -
Rule-based Queries: Queries objects in S3 using rules defined in
json-rules-engine.
Generates a signed HTTP request for secure interaction with AWS S3. This utility leverages AWS Signature V4 to compute request signatures.
Parameters:
-
body: Request payload. -
headers: Custom headers for the HTTP request. -
hostname: S3 bucket hostname. -
method: HTTP method (GET,PUT, etc.). -
path: S3 object path. -
protocol: Request protocol (http,https). -
service: AWS service (s3). -
authFacade: Handles user authentication through Cognito. -
cognitoSettings: AWS Cognito configuration.
To enable the aws_s3_entity CRUD adaptor plugin, import the Aws3Module in your Angular application. Ensure that AWS Cognito settings are configured.
Example:
import { Aws3Module } from 'aws3';
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: [Aws3Module],
providers: [{ provide: COGNITO_SETTINGS, useValue: cognitoSettings }],
})
export class AppModule {}The create method writes objects to an S3 bucket using a signed URL.
Example:
const crudInput = {
object: { id: '123', name: 'NewItem' },
params: { bucket: 'myBucket', prefix: 'myApp_' },
identity: () => of({ identity: 'uniqueKey' }),
};
s3EntityCrudAdaptorPluginFactory(...dependencies)
.create(crudInput)
.subscribe((response) => console.log('Create successful:', response.success));The read method retrieves an object from the S3 bucket (currently stubbed for development).
Example:
s3EntityCrudAdaptorPluginFactory(...dependencies)
.read({})
.subscribe((response) => console.log('Read successful:', response.success));The update method modifies an existing object in the S3 bucket.
Example:
const crudInput = {
object: { id: '123', name: 'UpdatedItem' },
params: { bucket: 'myBucket', prefix: 'myApp_' },
identity: () => of({ identity: 'uniqueKey' }),
};
s3EntityCrudAdaptorPluginFactory(...dependencies)
.update(crudInput)
.subscribe((response) => console.log('Update successful:', response.success));The delete method removes an object from the S3 bucket (currently stubbed for development).
Example:
s3EntityCrudAdaptorPluginFactory(...dependencies)
.delete({})
.subscribe((response) => console.log('Delete successful:', response.success));The query method retrieves objects from the S3 bucket based on rule conditions.
Example:
const queryInput = {
params: { bucket: 'myBucket', prefix: 'myApp_' },
rule: {
conditions: {
all: [
{ fact: 'identity', operator: 'startsWith', value: 'user' },
],
},
event: { type: 'visible' },
},
};
s3EntityCrudAdaptorPluginFactory(...dependencies)
.query(queryInput)
.subscribe((response) =>
console.log('Query successful, entities:', response.entities)
);-
s3EntityCrudAdaptorPluginFactorycreate(input: CrudOperationInput): Observable<CrudOperationResponse>read(input: CrudOperationInput): Observable<CrudOperationResponse>update(input: CrudOperationInput): Observable<CrudOperationResponse>delete(input: CrudOperationInput): Observable<CrudOperationResponse>query(input: CrudCollectionOperationInput): Observable<CrudCollectionOperationResponse>
-
createS3SignedHttpRequest(params: CreateSignHttpRequestParams): Observable<HttpRequest>- Generates signed HTTP requests for AWS S3 operations.
import { Aws3Module } from 'aws3';
@NgModule({
imports: [Aws3Module],
bootstrap: [AppComponent],
})
export class AppModule {}const input = {
params: { bucket: 'myBucket', prefix: 'myPrefix_' },
rule: {
conditions: {
all: [{ fact: 'identity', operator: 'startsWith', value: 'admin' }],
},
event: { type: 'visible' },
},
};
s3EntityCrudAdaptorPluginFactory(...dependencies)
.query(input)
.subscribe((response) => console.log('Queried entities:', response.entities));Example test for verifying create functionality:
describe('s3EntityCrudAdaptorPluginFactory', () => {
it('should create an item in S3', () => {
const input = {
object: { id: 'item1', name: 'TestName' },
params: { bucket: 'test-bucket', prefix: 'testPrefix_' },
identity: () => of({ identity: 'itemKey1' }),
};
s3EntityCrudAdaptorPluginFactory(...dependencies)
.create(input)
.subscribe((response) => expect(response.success).toBeTruthy());
});
});The AWS3 Angular library provides secure integration with AWS S3 using signed URLs and Cognito-based authentication. It is ideal for applications requiring scalable, secure object storage with advanced querying capabilities.
For contributions, issues, or feature requests, feel free to contact us!