Forem: Tanja Bayer

Vector Search Demystified: A Guide to pgvector, IVFFlat, and HNSW

Tanja Bayer — Tue, 25 Feb 2025 18:00:00 +0000

Vector Databases: The Engine Behind Modern AI Applications

In an era where AI is reshaping how we interact with data, vector databases have emerged as the unsung heroes powering everything from Netflix recommendations to ChatGPT's semantic understanding. Let's decode why they're becoming the backbone of intelligent applications—and how to choose the right approach for your needs.

The Rise of Vector Search: More Than Just Keywords

Remember the old days of exact-match search? Type "running shoes" and pray the product had those exact words in its title. Vector databases changed the game entirely. Now your search for "comfortable athletic footwear" finds those perfect Nike Air Max sneakers—even if they never used those exact words in their description.

"Traditional databases are like dictionaries—great for looking up exact words. Vector databases are like having a librarian who understands what you mean, not just what you say."

What Makes Vector Databases Special?

Vector databases store data as mathematical coordinates in high-dimensional space. Think of it like this:

Traditional Database: "Does this word match exactly?"
Vector Database: "How close is this concept to what we're looking for?" This fundamental shift enables:

Semantic Search: Understanding meaning, not just matching text
Recommendation Systems: Finding truly similar items
AI-Powered Features: Natural language processing at scale
Image and Audio Search: Finding visual or sonic similarities

The Technical Foundation: Vector Embeddings

At their core, vector databases work with embeddings—numerical representations of data in multi-dimensional space. Here's what that means in practice:

# Example: Word embeddings
"cat" → [0.2, 0.5, -0.1, 0.8, ...]
"kitten" → [0.3, 0.4, -0.2, 0.7, ...]
"dog" → [-0.1, 0.6, 0.2, 0.3, ...]

These vectors capture semantic relationships. Similar concepts end up closer together in this mathematical space.

Choosing Your Vector Index: IVFFlat vs. HNSW

When implementing vector search with pgvector, you'll face a crucial decision between two indexing methods. Here's the practical breakdown:

IVFFlat: The Efficient Workhorse

Build Time: ️ Fast
Memory Usage: Lower
Query Speed: Moderate
Best For: Smaller datasets, limited resources

HNSW: The Speed Demon

Build Time: Slower
Memory Usage: Higher
Query Speed: Very Fast
Best For: Production apps needing quick responses

Real-World Decision Matrix

Requirement	IVFFlat	HNSW
Dataset < 1M vectors	✅	✅
Low memory environment	✅	❌
Sub-10ms queries needed	❌	✅
Frequent updates	❌	✅
Quick initial setup.	✅	❌

Performance in Numbers

Results of a dataset of around 1M vectors of 50 dimensions. With 10K queries and 10 nearest neighbors.

Build Time:
- IVFFlat: 128 seconds
- HNSW: 4065 seconds
Query Speed:
- IVFFlat: 2.6 QPS
- HNSW: 40.5 QPS
Memory Usage:
- IVFFlat: 257MB
- HNSW: 729MB

Resource

Best Practices & Implementation Tips

Start Simple
- Begin with IVFFlat unless you know you need HNSW's speed
- Measure real-world query patterns before optimizing
Monitor & Maintain
- Track query times and accuracy
- Schedule regular index rebuilds for IVFFlat
- Monitor memory usage, especially with HNSW
Optimize Gradually
- Start with default parameters
- Tune based on actual performance metrics
- Consider A/B testing different configurations

Looking Forward: The Future of Vector Search

As AI continues to evolve, vector databases will become even more crucial. We're seeing exciting developments in:

Hybrid searches combining vector and traditional queries
Automated index optimization
Hardware acceleration for vector operations

Next Steps

Ready to implement vector search in your application?

Start Small: Test with a subset of your data
Measure: Benchmark what matters for your use case
Scale: Choose the right index based on real requirements

Want to dive deeper? Join our community Discord.

Remember: The best vector database implementation is the one that meets your specific needs - not necessarily the one with the most impressive benchmark numbers.

How to Set Up a GitHub Actions Self-Hosted Runner on macOS 15+

Tanja Bayer — Wed, 05 Feb 2025 09:37:48 +0000

Migrating to GitHub offers numerous advantages, but it also presents opportunities to optimize your workflow environment. In our journey, we aimed to reduce operational costs without sacrificing the flexibility required for our continuous integration and deployment (CI/CD) processes. By setting up self-hosted runners on macOS 15+, we gained control over our build environment while managing expenses effectively. This guide will walk you through the steps we took, the challenges we faced, and how you can implement a similar setup.

Introduction

In an effort to optimize costs while maintaining the flexibility of our CI/CD pipelines, we decided to set up self-hosted runners on macOS after migrating from Bitbucket to GitHub. Self-hosted runners allow us to use our own infrastructure (using all the idle capacity of our powerful developer MacBooks) for running GitHub Actions workflows, which can lead to significant cost savings, especially when dealing with resource-intensive tasks or macOS-specific builds.
However, the process wasn't without its hurdles. We encountered several challenges, particularly with setting up the runners as services on macOS 15+. This guide aims to help you navigate these challenges and set up your own self-hosted runners efficiently.

General Setup of a Self-Hosted Runner

Setting up a self-hosted runner involves adding the runner to your GitHub organization and configuring it on your macOS machine.

Adding a Self-Hosted Runner to Your Organization

Navigate to Your Organization on GitHub:

Go to the main page of your GitHub organization.
Under your organization name, click on Settings.

Access Runners Settings:
- In the left sidebar, click Actions.
- Then, click on Runners.
Add a New Runner:
- Click New runner, then select New self-hosted runner.
Choose Operating System and Architecture:
- Select macOS as the operating system.
- Choose the appropriate architecture (usually x64 ).
Follow Setup Instructions:
- GitHub will provide you with a series of shell commands.
- Open a terminal on your macOS machine.
- Run each command in order to download and configure the runner application.

Verifying the Runner

After completing the setup:

Ensure the runner is listed under Runners in your organization's settings.
The terminal should display:
Code kopieren
√ Connected to GitHub [Timestamp]: Listening for Jobs This means your runner is active and ready to accept jobs.

Configuring the Runner as a Service on macOS 15+

Running the self-hosted runner as a service ensures it starts automatically and runs in the background.

Installing the Service

Stop the Runner Application:

If the runner is currently running, stop it by pressing Ctrl + C in the terminal.

Install the Service

Navigate to your runner's directory in the terminal.
Run the following command:

./svc.sh install

Starting the Service

Start the service with:

./svc.sh start

Checking the Service Status

Check if the service is running correctly:

./svc.sh status

Stopping and Uninstalling the Service

Stop the Service

./svc.sh stop

Uninstall the Service

./svc.sh uninstall

Prioritizing Self-Hosted Runners in Workflows

To optimize resource usage, you can configure your workflows to prioritize self-hosted runners but fall back to GitHub-hosted runners if none are available.
Modifying Your Workflow YAML
Add the following jobs to your workflow file:

jobs:
  check-runner:
    runs-on: ubuntu-latest
    outputs:
      runner-label: ${{ steps.set-runner.outputs.runner-label }}
    env:
      GH_TOKEN: ${{ secrets.ORG_RUNNER_STATUS_ACCESS_TOKEN }}
    steps:
      - name: Set runner
        id: set-runner
        run: |
          runners=$(gh api -H "Accept: application/vnd.github+json" /orgs/${{ github.repository_owner }}/actions/runners)
          available=$(echo "$runners" | jq '.runners[] | select(.status == "online" and .busy == false and .labels[] .name == "self-hosted")')
          if [ -n "$available" ]; then
            echo "runner-label=self-hosted" >> $GITHUB_OUTPUT
          else
            echo "runner-label=ubuntu-latest" >> $GITHUB_OUTPUT
          fi
  your-job:
    needs: check-runner
    runs-on: ${{ needs.check-runner.outputs.runner-label }}
    steps:
      # Your job steps here

Explanation

Check-Runner Job

Checks if any self-hosted runners are online and not busy. Sets runner-label to self-hosted if available, otherwise ubuntu-latest .

Your-Job :

Specifies runs-on dynamically based on runner-label . Ensures your job uses a self-hosted runner if available.

Setting Up Organization Secrets

Create an Access Token :

Generate a Personal Access Token (PAT) with read access to organization self hosted runners : Github Settings . This token is used to authenticate GitHub CLI commands in your workflow.

Add the Token to Organization Secrets :

Go to your organization settings on GitHub. Navigate to Secrets and variables > Actions > New organization secret . Name it ORG_RUNNER_STATUS_ACCESS_TOKEN and paste your PAT.

Common Pitfalls and Solutions

During our setup, we faced several issues. Here's how to solve them.

1. Permission Issues with Installing the Service

Problem:

Running ./svc.sh install fails due to permission issues with LaunchAgents.

Solution:

Grant read/write permissions to your user for the LaunchAgents directory:

sudo chown -R $(whoami) ~/Library/LaunchAgents/

2. Runner Not Showing as "Online"

Problem :

The runner remains offline, and the stderr.log file shows:

shell-init: error retrieving current directory: getcwd: cannot access parent directories: Operation not permitted /bin/bash: /path/to/actions-runner/runsvc.sh: Operation not permitted

Solution :

Grant Full Disk Access to Bash :

Open System Preferences > Security & Privacy > Privacy tab.
Scroll down and select Full Disk Access .
Click the lock icon to make changes and authenticate.
Click the + button to add an application.
Press Command + Shift + . to reveal hidden folders.
Navigate to /bin and select bash . Reinstall the Service : Stop and uninstall the service:

./svc.sh stop 
./svc.sh uninstall

Reinstall and start the service:

./svc.sh install 
./svc.sh start

Conclusion

By setting up self-hosted runners on macOS 15+, we achieved significant cost savings without compromising on the flexibility of our CI/CD pipelines. This hybrid approach allows us to utilize our own infrastructure when available and seamlessly fall back to GitHub-hosted runners when necessary.

Key takeaways:

Cost Optimization : Self-hosted runners reduce reliance on paid GitHub-hosted runners, lowering operational costs.
Flexibility : Maintaining the ability to run workflows on GitHub-hosted runners ensures builds are not stalled due to unavailable resources.
Control Over Environment : Self-hosted runners provide full control over the software and hardware environment.

Mastering Angular SSR: Enabling Custom HTTP Responses (404, 301)

Tanja Bayer — Wed, 08 May 2024 06:26:22 +0000

Welcome to the first post in our series on optimizing Angular apps for search enginge optimisation (SEO)! In this post, we'll walk you through enabling your Angular app to return custom HTTP responses, such as 404 (Not Found) and 301 (Permanent Redirect), using Angular SSR.

Why is This Important?

When optimizing your Angular app for SEO, it's crucial to provide the correct HTTP status codes. Here's why returning accurate 404 and 301 responses improves SEO over always returning a 200 status:

Search Engine Understanding:

404 (Not Found): When search engines encounter a 404 status, they understand that the page does not exist. This prevents them from indexing non-existent content, which could lead to penalties for having "soft 404" pages (pages that return a 200 status but have no useful content).
301 (Permanent Redirect): Tells search engines that the requested URL has permanently moved to a new location. This consolidates SEO value to the new URL, ensuring that link equity (backlinks, page authority) is transferred correctly.

Crawl Efficiency:

By signaling the correct 404 status for non-existent pages, search engines won't waste crawl budget trying to index irrelevant pages.
With a 301 status, search engines quickly find and index the new URL, improving the discoverability of updated content.

Improved User Experience:

While the user is still redirected internally or sees a custom 404 page, search engines receive accurate status codes that help them index the site correctly.
Ensuring users land on useful, relevant content reduces bounce rates and increases engagement.
By implementing 404 and 301 responses correctly, you ensure that search engines interpret your content accurately, improving your app's search visibility and overall user experience.

Implementation Details

To enable custom HTTP responses (404, 301) in your Angular 17+ app with built-in SSR support, follow these steps:

1. Soft 404 Component

In your component that handles soft 404 pages, inject the Response object conditionally to ensure it's only used server-side:

import { Response } from 'express';
import { CommonModule, isPlatformServer } from '@angular/common';
import { ChangeDetectionStrategy, Component, Inject, Optional, PLATFORM_ID, inject } from '@angular/core';

import { RESPONSE } from './server.token';

@Component({
    selector: 'app-soft-404',
    standalone: true,
    imports: [CommonModule],
    templateUrl: './soft-404.component.html',
    styleUrls: ['./soft-404.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class Soft404Component {
    platformId = inject(PLATFORM_ID);
    constructor(
        @Optional() @Inject(RESPONSE) private response: Response
    ) {
        // Only executes server-side
        if (isPlatformServer(this.platformId)) {
            this.response?.status(404);
        }
    }
}

2. Create a Response Token

Provide the Response token that you'll use for dependency injection (server.token.ts):

import { InjectionToken } from '@angular/core';

export const RESPONSE = new InjectionToken<Response>('RESPONSE');

3. 301 Redirect Component

In a component that handles redirects, use the Response object for server-side 301 redirection. If you're not on the server, navigate client-side with Angular Router.

import { CommonModule, isPlatformServer } from '@angular/common';
import { ChangeDetectionStrategy, Component, Inject, Optional, PLATFORM_ID, inject } from '@angular/core';
import { Router } from '@angular/router';

import { RESPONSE } from './tokens/server.token';

@Component({
    selector: 'app-redirect',
    standalone: true,
    imports: [CommonModule],
    templateUrl: './redirect.component.html',
    styleUrls: ['./redirect.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RedirectComponent {
    private readonly platformId = inject(PLATFORM_ID);

    constructor(
        private readonly router: Router,
        @Optional() @Inject(RESPONSE) private response: Response
    ) {
        const redirectUrl = '/new-url'; // Build your URL with your own logic

        if (isPlatformServer(this.platformId) && this.response) {
            this.response.redirect(301, redirectUrl);
            this.response.end();
        } else {
            this.router.navigate([redirectUrl]);
        }
    }
}

4. Update server.ts

Update server.ts to include the Response token and ensure proper error handling:


// All regular routes use the Angular engine
server.get('*', (req, res, next) => {
    commonEngine
        .render({
            bootstrap: AppServerModule,
            documentFilePath: indexHtml,
            url: `${req.protocol}://${req.headers.host}${req.originalUrl}`,
            publicPath: browserDistFolder,
            // Make sure to provide the RESPONSE here
            providers: [
                { provide: RESPONSE, useValue: res }
            ],
            inlineCriticalCss: true
        })
        // If the res.headersSent is true do not send again
        .then(html => (!res.headersSent ? res.send(html) : undefined))
        .catch((error: Error) => next(error));
});

By following these steps, your Angular app will be able to handle custom 404 and 301 responses accurately, improving both user experience and SEO.

Trouble Shooting

I you receive the error: Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client. Make sure you have the following line in your server.ts file.

.then(html => (!res.headersSent ? res.send(html) : undefined))

If you get the error: TypeError: Cannot read properties of null (reading 'status').
It looks like you are running your app in development mode and forgot to mark the this.response as optional. Make sure you add the ?. The RESPONSE is only injected on a production build.
If you receive the error: Error [NullInjectorError]: R3InjectorError(Standalone[_a])[InjectionToken RESPONSE -> InjectionToken RESPONSE -> InjectionToken RESPONSE -> InjectionToken RESPONSE]
It seems you forgot to mark the RESPONSE injection as Optional. In your constructur check you added the @Optional() before the @Inject(RESPONSE).

Final Thoughts

Now your Angular app is capable of returning 404 and 301 HTTP responses! Server-side rendering helps provide better responses and search engine optimization. Stay tuned for the next blog post in this series, where we dive deeper into enhancing SSR performance and improving SEO.

What other topics are you interested in related to Angular an SEO? Let me know, I am always on the search for new topics to write about.

Hey there, dear readers! Just a quick heads-up: we're code whisperers, not Shakespearean poets, so we've enlisted the help of a snazzy AI buddy to jazz up our written word a bit. Don't fret, the information is top-notch, but if any phrases seem to twinkle with literary brilliance, credit our bot. Remember, behind every great blog post is a sleep-deprived developer and their trusty AI sidekick.

Mastering Log Retrieval in ECS Services: From Initial Trials to Advanced Solutions

Tanja Bayer — Tue, 16 Jan 2024 18:00:00 +0000

In the ever-evolving landscape of containerized applications, managing and accessing logs presents a universal challenge for developers and system administrators alike. Effective log management is crucial for maintaining operational efficiency, ensuring security, and facilitating prompt troubleshooting. However, the diverse nature of applications and the complexity of container orchestration platforms often turn log management into a daunting task. This blog post delves into a common yet intricate issue faced in log management within Amazon ECS (Elastic Container Service) environments. We encountered this challenge firsthand while working with various applications, including Shopware, where the intricacies of plugin-generated logs posed a unique set of hurdles. Our journey from an initial, straightforward approach to a more sophisticated and effective solution offers insights and lessons valuable for anyone grappling with similar log management challenges in containerized services.

The Problem

The challenge we faced was integrating Shopware's file-based logs into a centralized logging system like AWS CloudWatch. Unlike standard logging practices, Shopware writes logs to separate files, not the console, complicating their capture and monitoring in Amazon ECS environments.

The First Approach

Initially, we attempted to tackle the log integration issue using a configuration within supervisord.conf. Our strategy was to employ the tail command to continuously read the latest entries from Shopware's log files and redirect these entries to the standard output (stdout) and standard error (stderr). This method was designed to mimic the behavior of console logging, thereby facilitating the integration of these logs into AWS CloudWatch. The relevant part of our supervisord.conf looked something like this:

[program:prod_logs]
command=tail -f /sw6/var/log/prod*.log
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
autorestart=false
startretries=0

This setup aimed to ensure that all log data from Shopware's files were captured as if they were console outputs, theoretically allowing for seamless integration into CloudWatch.

However, we encountered a significant limitation. The tail command in our supervisor configuration was initiated at the start of the container's lifecycle. This meant that if the log files specified did not exist at startup (a common occurrence with dynamically created plugin logs), tail would fail to track these files, resulting in missed log entries. Consequently, this approach proved to be partially effective but not entirely reliable, especially for logs generated after the initial startup process.

Recognizing these limitations, we realized the need for a more robust solution that could dynamically adapt to the creation of new log files and ensure comprehensive log capture for our monitoring needs.

A Better Approach

Realizing the limitations of our initial method, we shifted our focus towards a more dynamic and robust solution: the implementation of the FireLens Log Driver in our ECS service. FireLens, a log router for Amazon ECS, offers the flexibility to route container logs to various destinations, including AWS CloudWatch, with enhanced processing capabilities.

We configured our ECS tasks to use FireLens, specifically utilizing Fluent Bit, an open-source log processor and forwarder. This setup enabled us to define custom log routing and processing rules, tailored to the unique structure of Shopware's log files.

Here’s an overview of how we configured FireLens with Fluent Bit:

Task Definition Enhancement: We modified our ECS task definitions to include the FireLens configuration, specifying Fluent Bit as the log router.
Custom Log Processing: Fluent Bit allowed us to create custom configurations to tail the Shopware log files, process the log data (like adding metadata, filtering, or transforming log formats), and then route them effectively to CloudWatch.
Dynamic Log File Handling: Unlike our initial approach, Fluent Bit's ability to dynamically detect and tail new log files resolved the issue of missing logs that were created after the container started.
Streamlined Integration: This setup streamlined the integration of Shopware’s logs into CloudWatch, ensuring that all log data, regardless of when it was generated, was consistently captured and made available for monitoring and analysis.

By leveraging FireLens's flexibility and Fluent Bit’s dynamic file tailing capabilities, we successfully integrated Shopware's logs into CloudWatch, enhancing our overall monitoring and operational efficiency in the ECS environment.

Implementation Details

Implementing the FireLens Log Driver in our ECS service involved several key steps. Below, I outline the process with generic code snippets, providing a blueprint that can be adapted to similar scenarios.

Configuring the Logs for the Firelens Container

First, we set up the FireLens container, ensuring that its logs, particularly errors, were captured for monitoring:

const containerLogDriver = LogDriver.awsLogs({
    streamPrefix: 'firelens', // Replace if you want
    logGroup: logGroup
});

FireLens Log Driver Setup

We configured the FireLens Log Driver with specific options to route logs to AWS CloudWatch

const fireLensLogDriver = new FireLensLogDriver({
    options: {
        Name: 'cloudwatch',
        region: 'your-region', // Specify the AWS region
        delivery_stream: 'application-stream-name', // Customize the stream name
        log_group_name: 'name-of-aws-log-group',
        log_stream_name: `/application/${uuid()}`, // Replace with a unique identifier
        log_key: 'log',
        auto_create_group: 'true'
    }
});

Task Definition for the Application Container

In the task definition for the application container, we included the FireLens Log Driver and specified mount points for log volumes:

const taskDefinition = new TaskDefinition(this, 'TaskDefinition', {
    // Task definition properties
    volumes: [
        // Other volumes
        { name: logVolumeName } // use a preferred name here
    ]
});

taskDefinition
    .addContainer('ApplicationContainer', {
        // Other container properties
        containerName: 'application',
        essential: true, 
        logging: fireLensLogDriver
    }).addMountPoints({
        sourceVolume: logVolumeName,
        containerPath: '/path/to/logs', // Path to the log directory for shopware /sw6/var/logs
        readOnly: false
    });

Custom FireLens Image

We created a custom Docker image for FireLens to tailor it to our specific needs. This involved starting with the base image from Amazon's AWS for Fluent Bit and adding our custom configuration:

# We run on ARM64, but you can use the x86 version just remove the platform part

FROM --platform=linux/arm64 amazon/aws-for-fluent-bit:latest 

RUN mkdir -p /sw6/var/log
ADD logConfig.conf /logConfig.conf

Fluent Bit Configuration: logConfig.conf

The logConfig.conf file is crucial as it defines how Fluent Bit will process and forward logs:

[INPUT]
    Name              tail
    Tag               container-logs
    # Change if you have another directory, according to the path in the
    Path              /sw6/var/log/*.log
    DB                /sw6/var/log/flb_service.db
    DB.locking        true
    Skip_Long_Lines   On
    Refresh_Interval  10
    Rotate_Wait       30

[OUTPUT]
    Name cloudwatch
    # make sure the part before -firelens* matches your container name in the task definition
    Match   shopware-firelens*
    region eu-west-1
    log_group_name shopware-$(ecs_cluster)
    log_stream_name /console/$(ecs_task_id)
    auto_create_group true
    retry_limit 2


    Name cloudwatch
    # use same name as in the Tag section of Input
    Match   container-logs
    region eu-west-1
    log_group_name shopware-$(ecs_cluster)
    log_stream_name /container/$(ecs_task_id)
    auto_create_group true
    retry_limit 2

This configuration allows us to tail all log files dynamically in the Shopware logs folder and manage console output effectively.

Adaptions to Dockerfile used in Service

If you encounter problems with your service - in our case shopware - writing to the log files, because of missing permissions make sure you create the DIR in your Dockerfile and mount it in your Docker

USER sw6
RUN mkdir -P /sw6/var/log && chown -R sw6:sw6 /sw6/var/log

VOLUME ["/sw6/var/log"]

Repository Creation and Docker Image Deployment

We then created a repository and deployed the custom Fluent Bit Docker image:

const tag = Date.now().toString();
const fluentbitRepository = new Repository(this, 'aws-for-fluentbit');

shopwareContainerRepository.grantPull(shopwareTaskDefinition.obtainExecutionRole());

new DockerImageDeployment(this, 'fluentbit-docker-image-deployment', {
    // make sure to specify the correct platform, which matches to the one specified in your Dockerfile
    source: Source.directory('/path/to/docker/fluent-bit/', { platform: Platform.LINUX_ARM64 }),
    destination: Destination.ecr(fluentbitRepository, {
        tag
    })
});

FireLens Log Router Configuration

Finally, we configured the FireLens log router with Fluent Bit:

taskDefinition
    .addFirelensLogRouter('firelog-router', {
        firelensConfig: {
            type: FirelensLogRouterType.FLUENTBIT,
            options: {
                configFileType: FirelensConfigFileType.FILE,
                configFileValue: '/logConfig.conf',
                enableECSLogMetadata: false
            }
        },
        logging: containerLogDriver,
        image: ContainerImage.fromEcrRepository(repository, tag),
        // Additional properties
        containerName: 'firelens-router',
        cpu: cpuValue,
        memoryLimitMiB: memoryValue
    })
    .addMountPoints({
        sourceVolume: logVolumeName,
        containerPath: '/path/to/logs', // Path to the log directory same as the one in the application container above
        readOnly: false
    });

Permission Policy for CloudWatch Logs

Lastly, we added a policy to the task role to allow the necessary actions for logging to CloudWatch:

const logPolicyStatement = new PolicyStatement({
    effect: Effect.ALLOW,
    actions: ['logs:CreateLogGroup', 'logs:CreateLogStream', 'logs:PutLogEvents', 'logs:DescribeLogStreams'],
    resources: ['*'] // Adjust as needed for specific log groups
});

shopwareTaskDefinition.addToTaskRolePolicy(logPolicyStatement);

These steps illustrate the general process we followed to configure FireLens with Fluent Bit for efficient log management. The configuration ensures dynamic log file handling and seamless integration of application logs into CloudWatch, significantly improving our monitoring and troubleshooting capabilities.

Conclusion

Our journey in mastering log retrieval in ECS services, particularly with Shopware, highlights the importance of adaptable and dynamic log management strategies in containerized environments. By moving from a basic supervisord.conf configuration to a more sophisticated approach using FireLens and Fluent Bit, we were able to overcome the challenges posed by file-based logging. This transition not only enhanced our ability to effectively integrate logs into AWS CloudWatch but also underscored the significance of choosing the right tools and configurations for specific use cases. Our experience demonstrates that with the right approach, even complex logging scenarios can be managed efficiently, ensuring comprehensive monitoring and analysis capabilities in cloud-based applications.

Resources:
AWS CDK Documentation

FluentBit ECS Log Collection

Creating a task definition that uses a FireLens configuration

Securing Your Serverless GraphQL API - Part III

Tanja Bayer — Tue, 18 Jul 2023 16:05:00 +0000

Welcome back, serverless security trailblazers! We've come a long way in our 'From Zero to Serverless Hero' series. In our previous chapter, we transitioned from the theoretical realm into the tangible world of implementation, securing our serverless GraphQL API with the power of AWS Cognito and a strong authorization setup.

In today's session, we push the boundaries of our serverless security prowess further. We're set to embark on a deeper exploration of the fascinating world of authorization. We're not just concerned with who can access our serverless API - but also the level and extent of their access. We'll decipher how to devise different access levels, meticulously tailoring permissions based on the roles of individual users.

This installment promises to be both challenging and enlightening, delving into the complexities of managing user permissions, all to add an extra layer of fortification to our serverless GraphQL API. At the end of this post, our serverless security expertise will have broadened significantly, and we'll be a few steps closer to reaching our ultimate goal.

Are you ready to level up your serverless security skills and go beyond the basics of API security? Let's move forward in our journey towards becoming the true serverless security heroes we aspire to be! It's time to roll up our sleeves, dive deep, and get started. The serverless saga continues!

Creating Custom Scopes
Restricting Access Bases on Scopes
Conclusion

Creating Custom Scopes

Before diving into the implementation part, let's quickly have a look on the theory. What are scopes and what are they used for? Scopes are like keys to the doors of our applications, opening the right passageways for users and restricting unnecessary or dangerous access.

In the OIDC world, scopes are used to specify what access a client has to a user's details and what information is available from the user's ID token and userinfo endpoint. They act as a mechanism for the client to express the desired granularity of requested permissions.

For example, a client could request the 'profile' scope to access the user's default profile information, such as name, picture, and locale. Or the client could request the 'email' scope to fetch user's email address. These scopes allow clients to function with the necessary user information while respecting the principle of least privilege - the concept that a client should only have access to the information it absolutely needs to perform its function.

Understanding and implementing scopes in your OIDC configuration is an important step in creating a secure and efficient serverless infrastructure. It allows for better control and a more personalized user experience.

You might be wondering: why are we going to implement custom scopes in our AWS Cognito setup, shouldn't Cognito support it out of the box because it is part of the OpenID definitions? Good question! Let's explore the rationale behind this move.

In the realm of AWS Cognito, scopes are akin to permissions that are attached to an OAuth 2.0 token. When an application requires an access token from AWS Cognito, it specifies the scopes it requires. These scopes correlate to the specific API operations the application needs to execute.

However, it's important to understand that, within AWS Cognito, scopes are not assigned on a per-user basis. Rather, they're linked to an application client or a resource server. This means that every user of a particular application client has access to the same scopes, which are defined by the client or by the resource server connected to that client.

Now, you might be wondering, what if I need user-specific permissions? This is a common requirement in many applications, but AWS Cognito itself doesn't provide this granularity. To handle this, you would typically need to include this logic within your application or API.

Consider a scenario where a request is made to your API. This request includes an access token from AWS Cognito. Upon receiving the request, your API would first verify this token, then extract the identity of the user. Once the user's identity is confirmed, your application would then use this identity to look up the specific permissions that apply to this user within your system.

This is precisely why we are venturing into the domain of custom scopes. Our goal is to have an efficient, robust system that allows us to manage permissions at a granular level, ultimately delivering a secure and user-specific experience.

Now we have reached the point where we need to update our UserModel, because it we will use it to store and check the scopes a user has:

import { Model, PartitionKey } from '@cubesoft/dynamo-easy';
import { ScopeEnum } from '../enums/scope.enum';

@Model({ tableName: 'user_table' })
export class UserModel {
  @PartitionKey()
  id: string;

  email: string;

  createdAt: number;
  updatedAt: number;

  scopes: ScopeEnum[];

  constructor() {
    this.createdAt = Date.now();
    this.updatedAt = this.createdAt;
  }
}

We add a array of scopes to our Model. Instead of using a string for the scopes we define a Scope enum which allows us to restrict the scopes to only specified scopes. This helps us to assign the correct scopes to a user. E.g. via an API:

export enum ScopeEnum {
  PLANT_READ = 'plant:read',
  PLANT_WRITE = 'plant:write',
}

Now that we have updated the model we would need to assign the new scopes to some of our users so that we will be able to check their scopes later. Normally you would provide this functionality via a mutation similar to a addPlant Mutation, and only users who have the user:write access would be allowed to access the mutation. However, as this is not significantly different than what we already did, we will skip this part and directly update the users in the database. In either way you need to do this one time by hand for one user, because if you restrict the user to a specific scope and no user has this scope already, you will be locked out via the api.

So we will do it just via the aws management console:

This gives the user the right to make changes on a plant and to view the plant object.

Restricting Access Bases on Scopes

Now that we have granted the user the access rights we need to make sure the api checks those rights, first we will update the authChecker to read the rights from the database:

export const customAuthChecker: AuthChecker<Context> = async (
  { context },
  roles
) => {
  if (!context.authToken) {
    throw new GraphQLError('No valid Token', {
      extensions: { code: 'FORBIDDEN' },
    });
  }
  await checkTokenAndUpdateUserId(context);

  const userService = Container.get<UserRepository>(UserRepository);
  console.log(context);
  const user = await userService.getUser(context.userId);

  context.scopes = user.scopes ?? [];

  // if the @Authorized() defines no roles
  if (roles.length === 0) {
    return true;
  }
  console.log('Check roles: ', roles);

  if (context.scopes.length === 0) {
    throw new GraphQLError('User lacks required role', {
      extensions: { code: 'FORBIDDEN' },
    });
  }

  // check roles if the @Authorized('ROLE') defines a role(s)
  if (context.scopes.some((role) => roles.includes(role))) {
    return true;
  }
  throw new GraphQLError('User lacks required role', {
    extensions: { code: 'FORBIDDEN' },
  });
};

Just updating our auth-checker like this we will see no changed behavior. To see the effect of this update we need to change the @Authorized decorator on our mutation:

  @Authorized(['plant:write'])
  @Mutation(() => PlantType, {
    description: 'Add a new plant to the library.',
  })
  async addPlant(
    @Arg('name', () => String) name: string,
    @Arg('description', () => String) description: string
  ): Promise<PlantType> {
    const plant = new PlantModel();
    plant.name = name;
    plant.description = description;

    return this.plantRepository.createOrUpdatePlant(plant);
  }

The new auth-checker needs access to read the data from the user table, so we need to add the following right in the serverless.stack.ts:

    userTable.grantReadWriteData(lambda);

Now we can deploy the change again with nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero

Afterwards we can check again in our playground, if we log in with a user without a scope we will receive an Unauthorized Error. If we log in with a user with the plant:write scope we will be able to execute the addPlant mutation.

Conclusion

In today's installment of our 'From Zero to Serverless Hero' series, we've further deepened our understanding of AWS Cognito and the intricate role of scopes within our serverless infrastructure. We've examined the way scopes are attached to an OAuth 2.0 token, acting as the gatekeepers of API operations that our applications need to perform.

However, we've also identified a critical point: In AWS Cognito, scopes are not user-specific. They are connected to an application client or a resource server, granting the same permissions to all users of a particular application client. For more granular, user-specific permissions, we have learned that the solution must be baked into our own application or API logic.

This realization has paved the way for us to explore custom scopes, setting the stage for us to build a system that can effectively manage user-specific permissions and deliver a tailored, secure experience. It's an exciting step forward on our journey to becoming serverless security heroes, as it introduces a new layer of depth to our understanding and capability.

As we wrap up this post, remember that the journey to mastering serverless security is akin to piecing together a complex puzzle. Every piece of information adds a new dimension, and every step we take gets us closer to seeing the whole picture.

Securing Your Serverless GraphQL API - Part II

Tanja Bayer — Wed, 05 Jul 2023 11:48:16 +0000

Welcome back, future serverless security heroes! In the previous instalment of our 'From Zero to Serverless Hero' series, we embarked on a theoretical exploration of API security in serverless GraphQL APIs. We've discussed the critical importance of API security and unveiled various strategic considerations that need to be taken into account.

Today, we shift gears from theory to practice. This time, we're getting our hands dirty, delving deep into the practical elements of API security and actually implementing the strategies we've previously discussed. The main goal? Transforming our knowledge into actionable intelligence, and, consequently, securing our serverless GraphQL API.

In this session, we will be focusing on two vital topics: AWS Cognito, a robust service for user authentication, and setting up authorization for secured data access. We will understand why AWS Cognito can be the perfect tool in our arsenal for handling user authentication and how we can successfully set it up. We will also unravel the mysteries of setting up authorization, thereby ensuring that data access is tightly controlled and only accessible to the appropriate users.

By the end of this post, we will be one step closer to our target of becoming not just serverless enthusiasts, but true serverless security heroes. Roll up your sleeves and prepare to dive into the technical deep-end of serverless GraphQL API security. The serverless journey continues, and this time, it’s all about the practicalities. Let's get started!

AWS Cognito: The Perfect Tool for User Authentication and Setting It Up
Setting Up Authorization for Secured Data Access
Conclusion

AWS Cognito: The Perfect Tool for User Authentication and Setting It Up

As we've discussed, user authentication is an integral part of API security. After exploring various solutions, AWS Cognito emerges as our choice for managing this crucial aspect. AWS Cognito is a comprehensive user identity and access management service that scales to millions of users, offers seamless integration with social identity providers, and comes with the robust support of Amazon's infrastructure.

In this section, we'll walk through a step-by-step guide on setting up AWS Cognito, detailing how to effectively leverage its features to secure our serverless GraphQL API.

Let's start with creating a cognito user pool, we will need the @aws-sdk/client-cognito-identity-provider library, first we will create a construct in src/construct/user-authentication.construct.ts to have clearly seperated functionalities, which increases code reusability:

import { CfnOutput, RemovalPolicy, Stack, custom_resources } from 'aws-cdk-lib';
import {
  AccountRecovery,
  StringAttribute,
  UserPool,
  UserPoolClient,
  UserPoolDomain,
} from 'aws-cdk-lib/aws-cognito';
import { Construct } from 'constructs';
import { getWorkspaceRoot } from '../utils/workspace';
import { lambda } from '../utils/lambda';
import { ITable } from 'aws-cdk-lib/aws-dynamodb';
import { Effect, Policy, PolicyStatement } from 'aws-cdk-lib/aws-iam';

import { join } from 'path';

interface UserAuthenticationProps {
  userTable: ITable;
}

export class UserAuthentication extends Construct {
  userPool: UserPool;
  webClient: UserPoolClient;

  constructor(scope: Construct, id: string, props: UserAuthenticationProps) {
    super(scope, id);

    this.userPool = new UserPool(this, 'user-pool', {
      standardAttributes: { email: { required: true, mutable: true } },
      customAttributes: {
        authChallenge: new StringAttribute({ mutable: true }),
      },
      passwordPolicy: {
        requireDigits: false,
        requireUppercase: false,
        requireSymbols: false,
      },
      accountRecovery: AccountRecovery.NONE,
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      removalPolicy: RemovalPolicy.DESTROY,
    });
    new UserPoolDomain(this, 'Domain', {
      userPool: this.userPool,
      cognitoDomain: {
        domainPrefix: 'serverless-hero', // Here you define your domain prefix
      },
    });

    const postConfirmationHandler = lambda(
      this,
      'post-auth',
      join(
        getWorkspaceRoot(),
        'dist/packages/serverless-api/post-auth',
        'handler.zip'
      ),
      {
        environment: {
          REGION: Stack.of(this).region,
          COGNITO_USER_POOL_ID: this.userPool.userPoolId,
        },
      }
    );

    // For being able to add the lambda triggers https://github.com/aws/aws-cdk/issues/10002 we can not add it directly with addTrigger, because of the userPoolId reference which would result in a circular dependency
    new custom_resources.AwsCustomResource(this, 'UpdateUserPool', {
      logRetention: 30,
      resourceType: 'Custom::UpdateUserPool',
      // https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-EmailConfiguration
      // https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsCustomResource.html
      onUpdate: {
        region: Stack.of(this).region,
        service: 'CognitoIdentityServiceProvider',
        action: 'updateUserPool',
        parameters: {
          UserPoolId: this.userPool.userPoolId,
          AutoVerifiedAttributes: ['email'],
          LambdaConfig: {
            PostConfirmation: postConfirmationHandler.functionArn,
          },
          Policies: {
            PasswordPolicy: {
              MinimumLength: 8,
              RequireLowercase: false,
              RequireNumbers: true,
              RequireSymbols: true,
              RequireUppercase: false,
            },
          },
        },
        physicalResourceId: custom_resources.PhysicalResourceId.of(
          this.userPool.userPoolId
        ),
      },
      policy: custom_resources.AwsCustomResourcePolicy.fromSdkCalls({
        resources: custom_resources.AwsCustomResourcePolicy.ANY_RESOURCE,
      }),
    });

    props.userTable.grantReadWriteData(postConfirmationHandler);
    this.userPool.addDomain('CognitoDomain', {
      cognitoDomain: {
        domainPrefix: 'serverless-hero',
      },
    });

    this.webClient = this.userPool.addClient('web-client', {
      authFlows: { custom: true },
    });
    // Using inline policy as a workaround to fix: https://github.com/aws/aws-cdk/issues/7016
    postConfirmationHandler.role?.attachInlinePolicy(
      new Policy(this, 'allow-update-user', {
        statements: [
          new PolicyStatement({
            effect: Effect.ALLOW,
            actions: ['cognito-idp:AdminUpdateUserAttributes'],
            resources: [this.userPool.userPoolArn],
          }),
        ],
      })
    );
    // You do not need this, it is only for logging the information in the end of the deployment process.
    new CfnOutput(this, 'user-pool-id', {
      value: this.userPool.userPoolId,
      description: 'User Pool ID',
    });

    new CfnOutput(this, 'client-id', {
      value: this.webClient.userPoolClientId,
      description: 'User Pool Client ID',
    });
  }
}

This looks a bit complicated and to some extend it is, because there are some tweaks required to get around some problems with the constructs which are used.
I added some comments directly in the code so you can understand why some parts are required.

What we are doing is creating a cognito pool, adding a custom domain prefix it. Then we are adding a lambda function which will do some processing once the user is signed up. Then we are adding a cognito client app, which we will need for doing a sign up/sign in. And in the end we are providing the required rights for the lambda function.

So, we have the cdk construct now, but what we are missing is the code implementing our logic. Let's do this now. We will start with the PostConfirmation lambda which gets called after the signup of a user and which allows us to do some processing on the data of the signed-up user. Here is the handler/post-auth.ts code:

import { CfnOutput, RemovalPolicy, Stack, custom_resources } from 'aws-cdk-lib';
import {
  AccountRecovery,
  StringAttribute,
  UserPool,
  UserPoolClient,
  UserPoolDomain,
} from 'aws-cdk-lib/aws-cognito';
import { Construct } from 'constructs';
import { getWorkspaceRoot } from '../utils/workspace';
import { lambda } from '../utils/lambda';
import { ITable } from 'aws-cdk-lib/aws-dynamodb';
import {
  Effect,
  Policy,
  PolicyStatement,
  ServicePrincipal,
} from 'aws-cdk-lib/aws-iam';

import { join } from 'path';

interface UserAuthenticationProps {
  userTable: ITable;
}

export class UserAuthentication extends Construct {
  userPool: UserPool;
  webClient: UserPoolClient;

  constructor(scope: Construct, id: string, props: UserAuthenticationProps) {
    super(scope, id);

    this.userPool = new UserPool(this, 'user-pool', {
      standardAttributes: { email: { required: true, mutable: true } },
      customAttributes: {
        authChallenge: new StringAttribute({ mutable: true }),
      },
      passwordPolicy: {
        requireDigits: false,
        requireUppercase: false,
        requireSymbols: false,
      },
      accountRecovery: AccountRecovery.NONE,
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      removalPolicy: RemovalPolicy.DESTROY,
    });
    new UserPoolDomain(this, 'Domain', {
      userPool: this.userPool,
      cognitoDomain: {
        domainPrefix: 'serverless-hero', // Here you define your domain prefix
      },
    });

    const postConfirmationHandler = lambda(
      this,
      'post-auth',
      join(
        getWorkspaceRoot(),
        'dist/packages/serverless-api/post-auth',
        'handler.zip'
      ),
      {
        environment: {
          REGION: Stack.of(this).region,
          COGNITO_USER_POOL_ID: this.userPool.userPoolId,
        },
      }
    );

    // For being able to add the lambda triggers https://github.com/aws/aws-cdk/issues/10002 we can not add it directly with addTrigger, because of the userPoolId reference which would result in a circular dependency
    new custom_resources.AwsCustomResource(this, 'update-user-pool', {
      logRetention: 30,
      resourceType: 'Custom::UpdateUserPool',
      // https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-EmailConfiguration
      // https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsCustomResource.html
      onUpdate: {
        region: Stack.of(this).region,
        service: 'CognitoIdentityServiceProvider',
        action: 'updateUserPool',
        parameters: {
          UserPoolId: this.userPool.userPoolId,
          AutoVerifiedAttributes: ['email'],
          LambdaConfig: {
            PostConfirmation: postConfirmationHandler.functionArn,
          },
          Policies: {
            PasswordPolicy: {
              MinimumLength: 8,
              RequireLowercase: false,
              RequireNumbers: true,
              RequireSymbols: true,
              RequireUppercase: false,
            },
          },
        },
        physicalResourceId: custom_resources.PhysicalResourceId.of(
          this.userPool.userPoolId
        ),
      },
      policy: custom_resources.AwsCustomResourcePolicy.fromSdkCalls({
        resources: custom_resources.AwsCustomResourcePolicy.ANY_RESOURCE,
      }),
    });
    const invokeCognitoTriggerPermission = {
      principal: new ServicePrincipal('cognito-idp.amazonaws.com'),
      sourceArn: this.userPool.userPoolArn,
    };

    postConfirmationHandler.addPermission(
      'InvokePostConfirmationHandlerPermission',
      invokeCognitoTriggerPermission
    );

    props.userTable.grantReadWriteData(postConfirmationHandler);
    this.userPool.addDomain('CognitoDomain', {
      cognitoDomain: {
        domainPrefix: 'serverless-hero',
      },
    });

    this.webClient = this.userPool.addClient('web-client', {
      authFlows: { custom: true },
    });
    // Using inline policy as a workaround to fix: https://github.com/aws/aws-cdk/issues/7016
    postConfirmationHandler.role?.attachInlinePolicy(
      new Policy(this, 'allow-update-user', {
        statements: [
          new PolicyStatement({
            effect: Effect.ALLOW,
            actions: ['cognito-idp:AdminUpdateUserAttributes'],
            resources: [this.userPool.userPoolArn],
          }),
        ],
      })
    );
    // You do not need this, it is only for logging the information in the end of the deployment process.
    new CfnOutput(this, 'user-pool-id', {
      value: this.userPool.userPoolId,
      description: 'User Pool ID',
    });

    new CfnOutput(this, 'client-id', {
      value: this.webClient.userPoolClientId,
      description: 'User Pool Client ID',
    });
  }
}

This code does two specific things:

It creates a user in DynamoDB, this way we will be able to store additional information for our user and are able to easily access this information later.
It checks if the login mail is lower case and if not it will correct the email to be lower case. Having a user sign up with a email containing uppercases letters might be a problem later so we apply this fix. But you are free to remove this part of the code.

As you can see the code uses a repository called UserRepository, as we did not create this one so far let's continue adding this code:

import Container, { Service } from 'typedi';

import {
  AdminUpdateUserAttributesCommand,
  CognitoIdentityProviderClient,
  CognitoIdentityProviderClientConfig,
} from '@aws-sdk/client-cognito-identity-provider';
import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { DynamoStore } from '@cubesoft/dynamo-easy';

import { UserModel } from '../model/user.model';
import { COGNITO_USER_POOL_ID } from '../token/cognito';
import { REGION } from '../token/env';

@Service()
export class UserRepository {
  private dynamoDb = new DynamoDB({ region: Container.get(REGION) });
  private cognitoUserPoolId = Container.get(COGNITO_USER_POOL_ID);
  private readonly userStore: DynamoStore<UserModel>;

  constructor() {
    this.userStore = new DynamoStore(UserModel, this.dynamoDb);
  }

  /**
   * Create a new user in cognito
   *
   * @param id Unique id of the user can be used for anonymised usage e.g in logs
   * @param email Email address of the user to create
   * @returns The created UserType
   */
  async createUser(id: string, email: string): Promise<UserModel> {
    const user = new UserModel();
    user.id = id;
    user.email = email;
    await this.userStore.put(user).exec();
    return user;
  }

  /**
   * Update a user in cognito
   *
   * @param email Email address of the user to update
   */
  async updateCognitoUserMail(
    userId: string,
    email: string,
    provider: CognitoIdentityProviderClientConfig = {}
  ): Promise<void> {
    const client = new CognitoIdentityProviderClient(provider);
    const command = new AdminUpdateUserAttributesCommand({
      Username: userId,
      UserPoolId: this.cognitoUserPoolId,
      UserAttributes: [
        {
          Name: 'email',
          Value: email,
        },
        {
          Name: 'email_verified',
          Value: 'true',
        },
      ],
    });
    const response = await client.send(command);
    if (response.$metadata.httpStatusCode !== 200) {
      throw new Error('Failed to create user');
    }
  }
}

For our userRepository to be able to store the user data in the database we need to create a UserModel:

import { v4 } from 'uuid';

import { Model, PartitionKey } from '@cubesoft/dynamo-easy';

@Model({ tableName: 'user_table' })
export class UserModel {
  @PartitionKey()
  id: string;

  email: string;

  createdAt: number;
  updatedAt: number;

  constructor() {
    this.createdAt = Date.now();
    this.updatedAt = this.createdAt;
  }
}

So let's recap: We created the construct for setting up cognito and provided the code for adding user data into our database. But we are not yet at the finish line, so far this will have no effect on our deployment. For the changes to take effect, we will need to add our construct into our stack, additionally we also need to create a table for storing information about our users later. For this we need to extend our lib/serverless-stack.ts with the following code snippet:

    const userTable = new Table(this, 'user-table', {
      tableName: `user_table`,
      billingMode: BillingMode.PAY_PER_REQUEST,
      removalPolicy: RemovalPolicy.DESTROY,
      partitionKey: { name: 'id', type: AttributeType.STRING },
    });

    new UserAuthentication(this, 'user-authentication', { userTable });

And we also need to add the function to our handler functions:

{
  "entrypoints": {
    "serverless-api": "src/handler/serverless-api",
    "post-auth": "src/handler/post-auth"
  }
}

Now we can deploy the code with our known command nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero.

Once we have deployed this changes we will be able to visit the Hosted Cognito UI for signing up or signing in a user.
The Hosted UI will look like this:

https://<your_domain>/login?response_type=token&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>

Where to find the required information?

your_domain: In the AWS Console go to Cognito > User Pools, select your newly created user pool. Go to the App Integration Tab, there you will find the Cognito Domain, but basically it is has the following structure https://<configured_prefix>.auth.<aws-region>.amazoncognito.com
your_app_client_id>: On the same page like your domain, scroll down to the App client list and you will find your Client ID
your_callback_url: In the same section as the Client ID click on the App client name, in the new page you will find all allowed callback URLs in the Hosted UI section. For a proper login process you will need to configure a callback URL which will redirect you to your website, however as we do not implement a UI in this blog post we do not care about the callback URL, we just need to make sure we provide one which is configured, if not Cognito will reject the login attempt.

If you provided all the correct variables you will be redirected to a UI similar like this.

After a successful signup you will be redirected to a url with the following structure:
<your_callback_url>/#id_token=<token>&expires_in=3600&token_type=Bearer

We are interested in the <token>. We will need it later for authenticating ourself to our api.

Setting Up Authorization for Secured Data Access

Now that we have all prerequits, we can extend our API to make sure only authenticated users will have access to specific routes.

We want to make sure only authenticated people are able to add new plants to our database. This for example allows us to track who made a change and in case we have some questions we would know who to contact. To apply this change we need to decorate our Mutation with the @Authorized() decorator:

  @Authorized()
  @Mutation(() => PlantType, {
    description: 'Add a new plant to the library.',
  })
  async addPlant(
    @Arg('name', () => String) name: string,
    @Arg('description', () => String) description: string
  ): Promise<PlantType> {
    const plant = new PlantModel();
    plant.name = name;
    plant.description = description;

    return this.plantRepository.createOrUpdatePlant(plant);
  }

Now the server knows it needs to check for the authorization of a user, but it does not yet know how to do this. For this we need to provide a helper function auth.checker.ts. For this function we need to install two packages npm i jwk-to-pem jsonwebtoken:

import { AuthChecker } from 'type-graphql';
import { Context } from '../model/context.model';
import { GraphQLError } from 'graphql';
import { Token } from '../interface/token.interface';
import jwkToPem from 'jwk-to-pem';
import { TokenExpiredError, decode, verify } from 'jsonwebtoken';

const keysCache = {};
const userPoolUrl = `https://cognito-idp.${process.env.REGION}.amazonaws.com/${process.env.COGNITO_USER_POOL_ID}`;

export const customAuthChecker: AuthChecker<Context, string> = async ({
  context,
}) => {
  if (!context.authToken) {
    throw new GraphQLError('No valid Token', {
      extensions: { code: 'FORBIDDEN' },
    });
  }
  checkTokenAndUpdateUserId(context);
  return true;
};

export async function checkTokenAndUpdateUserId(context: Partial<Context>) {
  let token: Token;
  try {
    const tokenParts = context.authToken.split('Bearer ');
    const authToken = tokenParts[tokenParts.length - 1];
    token = await verifyToken(authToken);
  } catch (err) {
    if (err instanceof TokenExpiredError) {
      throw new GraphQLError('Token is expired', {
        extensions: { code: 'FORBIDDEN' },
      });
    } else {
      throw new GraphQLError(err.message, {
        extensions: { code: 'FORBIDDEN' },
      });
    }
  }
  console.log(token);
  if (!token?.sub) {
    throw new GraphQLError('Token is not valid', {
      extensions: { code: 'FORBIDDEN' },
    });
  }
  context.userId = token.sub;
}
export async function verifyToken(
  rawToken: string
): Promise<Token | undefined> {
  const decodedToken = decode(rawToken, { complete: true });
  if (!decodedToken) {
    return undefined;
  }
  let pem = keysCache[decodedToken.header.kid];
  // this is a fallback to load a new set of keys
  // according to the documentation, this should be done in case of rotation
  if (!pem) {
    try {
      await loadKeys(userPoolUrl);
      pem = keysCache[decodedToken.header.kid];
    } catch (err) {
      console.error('Failed loading JWKS keys: ', err);
      return undefined;
    }
  }
  // if pem is still not found, the requestor is maybe using a wrong key (from other stage or forged)
  if (!pem) {
    throw new GraphQLError('Token is not supported', {
      extensions: { code: 'FORBIDDEN' },
    });
  }

  return verify(rawToken, pem, {
    issuer: userPoolUrl,
  }) as Token;
}

async function loadKeys(userPoolUrl: string): Promise<void> {
  const respones = await fetch(`${userPoolUrl}/.well-known/jwks.json`);
  const data = await respones.json();
  const keys = data.keys;
  for (const key of keys) {
    const pem = jwkToPem(key);
    keysCache[key.kid] = pem;
  }
  return;
}

This function does several things:

It checks if an authToken is provided
It verifies if the provided token is valid by loading the well-known jwks from cognito and using those for checking the validity of the token.
We take the userId from the encrypted token and add it to the context, so that it will be available during the mutation or query execution if required.

We used two unknown classes in this code, the contextModel:

export class Context {
  clientId: string;
  clientIp: string;
  authToken: string;
  // from auth.checker.ts
  userId?: string;
}

and the token interface:

export interface Token {
  sub: string;
  event_id: string;
  token_use: 'access';
  scope: string;
  auth_time: number;
  iss: string;
  exp: number;
  iat: number;
  jti: string;
  client_id: string;
  username: string;
  'cognito:groups': string[];
}

Now we need to make sure or server is able to perform the authorization check. For this we need to add the authChecker into the buildSchemaSync function and need to make sure the accessToken is properly added to our context:

const schema = buildSchemaSync({
  resolvers: [PlantLibraryResolver],
  container: Container,
  validate: { forbidUnknownValues: false },
  dateScalarMode: 'timestamp',
  authChecker: customAuthChecker,
});
const server = new ApolloServer({
  schema: schema,
  introspection: true,
  csrfPrevention: true,
});
export const handler = startServerAndCreateLambdaHandler(
  server,
  handlers.createAPIGatewayProxyEventV2RequestHandler(),
  {
    context: async ({ event }) => {
      const apiKey = getHeader('x-api-key', event.headers);
      if (!apiKey || !API_KEYS.includes(apiKey)) {
        throw new GraphQLError(
          'You are not authorized to perform this action.',
          {
            extensions: { code: 'FORBIDDEN' },
          }
        );
      }
      const authToken = getHeader('authorization', event.headers);
      const clientIp = event.requestContext.http.sourceIp;

      return {
        authToken,
        apiKey,
        clientIp,
      };
    },
  }
);

Additionaly, you might have seen that we are using two environment variables, COGNITO_USER_POOL_ID and REGION we need to make sure that those are available in our handler for this we need to add them during the function creation in our serverless.stack.ts.

    const lambda = new Function(this, 'api-handler', {
      runtime: Runtime.NODEJS_18_X,
      handler: 'serverless-api.handler',
      functionName: 'serverless-api',
      code: Code.fromAsset(
        join(
          getWorkspaceRoot(),
          'dist/packages/serverless-api/serverless-api',
          'handler.zip'
        )
      ),
      memorySize: Size.gibibytes(1).toMebibytes(),
      architecture: Architecture.ARM_64,
      logRetention: RetentionDays.ONE_DAY,
      timeout: Duration.seconds(5),
      environment: {
        COGNITO_USER_POOL_ID: userAuthentication.userPool.userPoolId,
        REGION: Stack.of(this).region,
      },
    });

Let's deploy the changes with nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero and see what effect it has.

If we now run our addPlant mutation from last time we will get a GraphQL Error with the message No valid Token. So it works, without the authorization header, we are no longer able to add a new plant. Let's to the check if it works with a correct token. For this we need to get the cognito token from section one and add this token in the header section in the Apollo Server Playground:

With this you should again get the expected output from your newly created plant.

Conclusion

We've now established AWS Cognito as a key tool in our serverless hero arsenal, leveraging its power to handle user authentication with finesse. Furthermore, we've successfully set up authorization to ensure our data access remains secure and uncompromised.

But remember, the journey to becoming a serverless security hero is one of continuous learning and constant improvement. Security is a dynamic field that demands consistent attention and updates. The work we've done today, though essential, represents only one facet of the broader API security landscape.

In the next session of our 'From Zero to Serverless Hero' series, we will delve deeper into the realm of authorization. We will explore how to tailor different levels of access based on the permissions granted to individual users. Managing user permissions adds an additional layer of security, enabling more granular control over who can access what within your serverless GraphQL API.

Stay tuned for our next adventure where we will take one more step closer to becoming full-fledged serverless security heroes. Remember, every piece of knowledge, every step we take, brings us closer to our goal. Until next time, keep learning, keep experimenting, and keep secure!’

Securing Your Serverless GraphQL API - Part I

Tanja Bayer — Tue, 20 Jun 2023 20:48:54 +0000

In the modern digital era, our reliance on APIs has become more pronounced than ever. As developers, we are tasked with building secure, scalable systems, and a significant part of that responsibility involves safeguarding the APIs that power these systems.

Over the course of our 'From Zero to Serverless Hero' series, we've taken a deep dive into creating a serverless environment, setting up an Apollo server with TypeGraphQL, and implementing data resolvers using Node.js. Now, our journey brings us to a critical stage: securing our serverless GraphQL API.

Security is a non-negotiable aspect of any application. In this post, we'll explore the importance of securing APIs, examine different strategies, and explain what combination is a good choice for the beginning.

By the end of this article, you'll have a much clearer understanding of API security. However, due to the extensive nature of this topic, we will focus more on the theory in this blog post and cover most of the implementation part in the next blog post. Strap in and prepare to level up from being just a serverless enthusiast to becoming a serverless security hero!

Understanding API Security
API Security Strategies
Our Choice for Security
Implementing Authentication in Your API
Testing the Security of Your API
Conclusion

Understanding API Security

API Security, at its core, involves implementing measures to protect the integrity of APIs from threats and attacks. APIs, or Application Programming Interfaces, are the conduits through which software applications communicate and exchange data. As such, they have become a prime target for malicious actors intent on exploiting vulnerabilities for data theft, denial of service attacks, and other nefarious purposes.

Securing your API is crucial because it serves as the gatekeeper to your application. If left unprotected, your API could serve as a weak point that attackers can exploit to access sensitive information. This risk is especially high in today's interconnected digital landscape, where APIs often interface with multiple external systems, each potentially introducing new vulnerabilities.

But what does it mean to secure an API? It involves several key aspects:

Authentication: This process verifies the identity of the client trying to access the API. It ensures that only recognized, authenticated users or systems are granted access.

Authorization: Once a user is authenticated, authorization determines what resources they can access and what operations they can perform. Not every user should have access to every part of your system.

Encryption: To safeguard data during transmission, APIs should use secure protocols such as HTTPS, which encrypts the data to prevent it from being intercepted and understood by unauthorized parties.

Input Validation: APIs should validate the input they receive to prevent attacks such as SQL injection or Cross-Site Scripting (XSS) that are designed to exploit poorly validated input.

Rate Limiting: This involves limiting the number of requests a client can make to the API within a specific timeframe, preventing DoS attacks where an attacker might aim to overwhelm an API with a flood of requests.

Auditing and Logging: Keeping a record of who accesses your API and what they do with it provides a trail that can be analyzed for suspicious activity. It also serves as a forensic tool if a breach does occur.
API security is not a 'set it and forget it' concept; rather, it is a continuous, proactive endeavor. It requires vigilance, regular updates, and a commitment to best practices in order to keep pace with evolving threats. In the following sections, we will discuss these aspects in greater detail, particularly focusing on our chosen strategy, user authentication.

API Security Strategies

There are numerous strategies and techniques at our disposal when it comes to securing APIs. The choice depends on a variety of factors, including the specific needs of the application, the sensitivity of the data being handled, and the nature of the clients that will be interacting with the API. Here, we'll outline a few commonly used API security strategies and briefly discuss their pros and cons.

1. API Keys

API keys are unique identifiers that are used to control access to an API. They are simple to implement and use. The client includes the API key in each request, and the server checks this key to decide whether or not to process the request.

Pros: Easy to use; straightforward implementation.

Cons: API keys are not inherently secure. If a key is stolen, it can be used to gain unauthorized access to the API. Also, API keys alone can't provide fine-grained control over what resources a client can access.

2. OAuth

OAuth is an open standard for access delegation. It allows users to grant third-party applications access to their information on other services, without sharing their passwords.

Pros: Highly secure; allows for fine-grained access control; widely adopted standard.

Cons: Can be complex to implement; involves a multi-step process for the user, which can affect the user experience.

3. JSON Web Tokens (JWT)

JWT is a standard for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

Pros: Enables stateless authentication; allows for fine-grained access control.

Cons: Requires careful management of the token lifecycle; vulnerable to theft if not properly secured.

4. Mutual TLS (mTLS)

mTLS is a version of the standard TLS protocol where both the client and the server authenticate each other. This mutual authentication provides an additional layer of trust.

Pros: Provides strong, mutual authentication.

Cons: Requires the distribution and management of client certificates, which can be complex.

5. GraphQL Shield

GraphQL Shield is a library specifically for the GraphQL server, offering an easy-to-use middleware-style API to create a permission layer for your application.

Pros: Easy integration with GraphQL; flexible rule-based access control.

Cons: Specific to GraphQL; requires an understanding of its rule and permission system.

Each of these strategies has its strengths and weaknesses, and there's no 'one-size-fits-all' answer. You might even use a combination of these strategies for different aspects of your API. In our case, we've chosen user authentication as our primary strategy, and we will use AWS Cognito to implement it. In the next sections, we'll discuss why we made this choice and how to get it set up.

Our Choice for Security: User Authorization and Authentication via ApiKeys and OAuth

Striking the right balance between accessibility and security is essential when designing APIs. Some functionalities, such as browsing through a library, should be accessible to all users, even those who aren't logged in. However, other actions, particularly those that alter data or user preferences, need stricter control. To address these needs, we've opted for a dual approach for our serverless GraphQL API: ApiKeys for public endpoints and OAuth for protected operations.

ApiKeys for Public Endpoints

ApiKeys provide a simple, effective way to regulate access to our API's public-facing endpoints. Users can engage with aspects of our service, such as browsing the library, without logging in. ApiKeys simplify user experience for new or casual users while offering control through unique keys issued to each client. By limiting the number of requests a client can make within a certain timeframe, we ensure these public endpoints are not exploited or overloaded.

OAuth for Protected Operations

When it comes to sensitive operations like changing user settings or updating records, we need more robust protection. That's where OAuth comes in. OAuth is a widely used standard that allows for user-specific authorization and authentication. Using OAuth, we can confirm the identity of users, grant them access, and control what operations they can perform once logged in. This protects sensitive data and functionalities, enhancing our API's security.

A Balanced Approach

This blend of ApiKeys and OAuth offers a balanced, secure, and user-friendly API. ApiKeys ensure public services are accessible, attracting potential users to our application. OAuth, meanwhile, protects sensitive operations, offering peace of mind for users and administrators alike. This approach effectively combines robust security with an optimal user experience. In the next sections, we'll explore how to implement these ApiKeys. The implementation of authorization with OAuth will be covered in the next blog post.

Implementing Authentication in Your API with an API Key

Let's start with the easy one: checking if the user provides a valid ApiKey. For this, we will check the headers in the context, and if the required x-api-key header is not provided or the apiKey is not in our whitelist, we will throw an error.

const API_KEYS = ['your-key'];

export const handler = startServerAndCreateLambdaHandler(
  server,
  handlers.createAPIGatewayProxyEventV2RequestHandler(),
  {
    context: async ({ event, context }) => {
      const apiKey = getHeader('x-api-key', event.headers);
      if (!apiKey || !API_KEYS.includes(apiKey)) {
        throw new GraphQLError(
          'You are not authorized to perform this action.',
          {
            extensions: { code: 'FORBIDDEN' },
          }
        );
      }
      return {
        lambdaEvent: event,
        lambdaContext: context,
      };
    },
  }
);

In the above example we add a list of api keys via a variable in the code. However, for easier configuration putting this into a database or at least making it configurable via environment variables would be the recommended option.

We also used a helper function in the above code, it will just get the header values from the header helper/grapqhl.helper.ts:

export function getHeader(
  headerName: string,
  headers: { [id: string]: unknown }
): string | undefined {
  const keys = Object.keys(headers);
  const key = keys.find((k) => k.toLowerCase() === headerName.toLowerCase());
  if (key) {
    return headers[key] as string;
  } else {
    return undefined;
  }
}

Add the above snippets to your API handler, build and deploy the code, and check how your API behaves now.

If you query your server now, you will get a 500 server response with the code UNAUTHENTICATED in the error message.

From now on you need to provide your apiKey with every call query and mutation you make. In the Apollo Playground, you are able to configure this header in a specific tab:

As easy as this, now only people who know your apiKeys are able to communicate with your API.

Testing the Security of Your API

After implementing the security measures for your API, it's critical to ensure that they work as expected. Testing the security of your API is a continuous process that helps identify potential vulnerabilities and ensure that the implemented security mechanisms function correctly.

1. Unit Testing: Start with unit tests for your authentication and authorization code. Ensure that only authenticated users can access protected routes, and are authorized to perform the operations they're trying to carry out.

2. Integration Testing: Conduct integration tests where you simulate a user's interaction with the API, performing various tasks. Check that the system correctly identifies users and grants them appropriate permissions.

3. Penetration Testing: Here, you simulate an attack on your system to identify potential vulnerabilities. Use automated tools, and, if possible, consider hiring a security firm that specializes in this type of testing. Test for common attack vectors such as SQL Injection, Cross-Site Scripting (XSS), and Cross-Site Request Forgery (CSRF).

4. API Scanning: Use API security scanners that can scan your APIs for vulnerabilities. These tools can help find issues that could be exploited by an attacker.

5. Load Testing: Overloading an API can reveal security vulnerabilities. Simulate high load situations to make sure that your rate limiting is effective and the system doesn't reveal sensitive information under stress.

6. Regular Auditing: Regularly review your security logs to identify any suspicious activity. Automated auditing tools can flag unusual behavior, making it easier to catch and respond to potential security threats.

7. Dependency Checking: Regularly check your dependencies for known vulnerabilities. Tools exist that can automatically check for and alert you to security issues in your dependencies.

8. Security Training: Keep your team up-to-date with the latest security best practices and common threats. A well-informed team is one of your best defenses against security breaches.

Remember, security isn't a one-time event but a continuous process of improvement. Regular testing, auditing, and updating your security measures are key to maintaining a robust, secure API. Stay proactive and vigilant in order to keep your API—and your users' data—safe and secure.

Conclusion

In our journey from zero to serverless hero, understanding and implementing robust security measures is of paramount importance. In this post, we've explored the essentials of API security and strategies to safeguard our serverless GraphQL API.

We've elucidated why a mix of ApiKeys and OAuth provides a well-rounded security solution, allowing both public access to certain services and stringent protection for sensitive operations. This balance between openness and security forms the cornerstone of an effective, user-friendly, and secure API.

Furthermore, we've underscored the importance of continuous testing to validate the effectiveness of our security implementations, and to proactively uncover and patch potential vulnerabilities.

Implementing these strategies, however, is not the end. Security is a dynamic and continuous process. It requires regular evaluation and updates to keep up with the ever-evolving landscape of digital threats.

In the end, the key to effective API security lies not just in a one-time setup, but in continuous vigilance, regular testing, and an unwavering commitment to protecting your data and your users. Through this post, we hope to have equipped you with a good base of knowledge about API security. In the next blog post, we will head to the implementation part. So stay tuned.

Implementing Data Resolvers with Node.js

Tanja Bayer — Tue, 06 Jun 2023 19:15:00 +0000

Welcome back to our series on working with GraphQL, Node.js, and Apollo Server. In our previous posts, we set up our serverless environment and configured our Apollo Server with TypeGraphQL. We even created our first basic resolver. It's been quite a journey, but we're only just getting started.

Today, we're going to delve deeper into the exciting world of data resolvers. As we know, resolvers play a crucial role in a GraphQL server, acting as the bridge between our schema and the data we need to fetch from various sources. They're what make GraphQL such a dynamic and efficient tool for developers.

In this post, we will enhance our understanding of data resolvers. We'll start by exploring how to query data from a database using resolvers. We'll then venture into the integration of external APIs into our GraphQL server — a powerful way to leverage additional data sources and functionality. From there, we'll turn our attention to mutations, allowing us to not only fetch data but also modify it. To wrap it all up, we'll discuss some best practices for working with resolvers.

By the end of this blog post, you'll have a robust understanding of data resolvers and how to utilize them effectively within your Node.js and Apollo Server setup. Let's jump right in!

Querying Data from a Database

Up until now, we've been focusing on building the structure of our GraphQL server, without working with any persisted data. All our operations so far have dealt with data held temporarily in memory. But to develop a fully functional, real-world application, we need a persistent storage system - a database.

That's where we're heading in this section. We'll take a crucial step forward in our project and set up a database. To achieve this, we'll use Amazon DynamoDB.

Amazon DynamoDB is a fast, fully managed NoSQL database service from AWS, offering seamless scalability and reliable performance. Ideal for applications requiring single-digit millisecond latency, it provides a key-value and document data model that enables flexible, dynamic schemas. Its compatibility with GraphQL makes it a robust choice for modern web applications.

Not only is it a powerful, flexible, and high-performance NoSQL database service, but it also happens to be part of the AWS Free Tier. This means we can experiment and build our knowledge without incurring extra costs, making it an ideal choice for our exploration of GraphQL. You can check out all the details of the AWS Free Tier, including DynamoDB, at this link. So, let's get started with setting up our DynamoDB!

Setting Up The Database

We need to put this snippet into our serverless.stack.ts file. This creates a database with the table name data_table and afterwards we grant read and write access to our lambda.

const dataTable = new Table(this, 'data-table', {
   tableName: `data_table`,
   timeToLiveAttribute: 'ttl',
   billingMode: BillingMode.PAY_PER_REQUEST,
   removalPolicy: RemovalPolicy.DESTROY,
   partitionKey: { name: 'id', type: AttributeType.STRING },
});
dataTable.grantReadWriteData(lambda);

Updating the Resolver and Accessing the Data

Now that we have created the database we need to create a repository for adding, accessing, updating and deleting data in the database. We will use dynamo-easy for this, a wrapper around the AWS dynamodb client, written by shiftcode which does the data mapping to typescript object by using decorators. We will use a fork of it because we want to use the aws sdk v3 version with some additional fixes added. Let's install it via npm i @cubesoft/dynamo-easy typedi @types/uuid. Now that we have it installed, let's create the repository and our data model. Let's pretend we want to create a database with plants. There are several different classes we need to create.

The interface/plant.interface.ts, which will be used as an interface for our plant model to make sure all inheriting classes have all required fields.

export interface PlantInterface {
  id: string;

  name: string;
  description?: string;

  createdAt: number;
  updatedAt: number;
}

The model/plant.model.ts file, which represents our plant object for storing it in dynamodb:

import { v4 } from 'uuid';

import { Model, PartitionKey } from '@cubesoft/dynamo-easy';
import { PlantInterface } from '../interface/plant.interface';

@Model({ tableName: 'data_table' })
export class PlantModel implements PlantInterface {
  @PartitionKey()
  id: string;

  name: string;
  description?: string;

  createdAt: number;
  updatedAt: number;

  constructor() {
    this.id = v4();
    this.createdAt = Date.now();
    this.updatedAt = this.createdAt;
  }
}

The repository/plant.repository.ts file, for storing and retrieving the data from dynamodb:

import { Service } from 'typedi';

import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { DynamoStore } from '@cubesoft/dynamo-easy';

import { PlantModel } from '../model/plant.model';

@Service()
export class PlantRepository {
  private dynamoDb = new DynamoDB({ region: 'eu-central-1' });

  async createOrUpdatePlant(plant: PlantModel): Promise<void> {
    const store = new DynamoStore(PlantModel, this.dynamoDb);
    await store.put(plant).execFullResponse();
  }

  async deletePlant(id: string): Promise<void> {
    const store = new DynamoStore(PlantModel, this.dynamoDb);
    return store.delete({ PartitionKey: id }).exec();
  }

  async getPlant(id: string): Promise<PlantModel> {
    const store = new DynamoStore(PlantModel, this.dynamoDb);
    return store.get(id).exec();
  }
}

The model/plant.type.ts file which represents our plant model annotated with the necessary decorators so that they will appear in our GraphQL Schema. It is good to provide an ID field type for every model, because this helps Apollo when identifying unique objects for it's caching mechanism.

import { PlantInterface } from '../interface/plant.interface';
import { Field, Float, ID, ObjectType } from 'type-graphql';

@ObjectType('PlantType', { description: 'Object representing a plant' })
export class PlantType implements PlantInterface {
  @Field(() => ID)
  id: string;

  @Field(() => String)
  name: string;

  @Field(() => String, { nullable: true })
  description?: string;

  @Field(() => Float)
  createdAt: number;

  @Field(() => Float)
  updatedAt: number;
}

Last but not least we need to update our resolver so that it will actually use the new models and is able to read from the database. I renamed the resolver and put it in in a file resolver/plant.resolver.ts. Instead of returning a string now, our new query getPlant will return a list of plants from dynamodb.

If you like me did also update the name of the resolver from last time, make sure to update the name also in our handler/serverless-api.ts file:

const schema = buildSchemaSync({
  resolvers: [PlantLibraryResolver],
  container: Container,
  validate: { forbidUnknownValues: false },
  dateScalarMode: 'timestamp',
});

Now we can build and deploy our api again using nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero.

When we open our Apollo Playground this time we will see the updated query:

And if you execute the query you will get an empty array, because we did not yet add any plants to our database, which can be returned. For this we will have a look at mutations in the next section.

Handling Mutations

In the realm of GraphQL, while queries allow us to fetch and read data, mutations empower us to modify data. Essentially, mutations are operations that can create, update, or delete data in our backend - be it a database or another data source.

Understanding and implementing mutations is crucial for any application that requires dynamic user interactions. From adding a product to a shopping cart, updating user details, to deleting an old post, all these operations rely on mutations. It's through mutations we shape and reshape our data, creating a more interactive and responsive user experience.

So let's create a mutation for adding a plant to our database:

import 'reflect-metadata';
import { Arg, Mutation, Query, Resolver } from 'type-graphql';
import { PlantType } from '../model/plant.type';
import { PlantRepository } from '../repository/plant.repository';
import { Service } from 'typedi';
import { PlantModel } from '../model/plant.model';

@Service()
@Resolver()
export class PlantLibraryResolver {
  constructor(private readonly plantRepository: PlantRepository) {}
  @Query(() => [PlantType], {
    description: 'Returns a list of plants.',
  })
  async getPlants(): Promise<PlantType[]> {

    return this.plantRepository.listPlants();
  }

  @Mutation(() => PlantType, {
    description: 'Add a new plant to the library.',
  })
  async addPlant(
    @Arg('name', () => String) name: string,
    @Arg('description', () => String, {nullable:true}) description?: string
  ): Promise<PlantType> {
    const plant = new PlantModel();
    plant.name = name;
    plant.description = description;

    return this.plantRepository.createOrUpdatePlant(plant);
  }
}

We add a new function addPlant to the resolver and annotate it with the @Mutation decorator. The function will take two inputs a variable name of type string and an optional variable description of type string, in TypeGrapQL we need to add the {nullable:true} in the decorator to tell TypeGrapQL that the variable is optional.

After deploying your last change with nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero you will now be able to use the mutation and add your first plant in the Apollo Playground:

Now you can run your Query again and you will get an array with your new plant item. You did it, you have written your first mutation in a lambda function.

Conclusion

In this post, we delved into the essentials of interacting with a database using Apollo Server and DynamoDB, from setting up the database to querying data. We also introduced mutations, crucial operations for changing data, and explained their various use cases.

We encourage you to apply what you've learned here to your own projects. Experiment with different types of queries, API integrations, and mutations. Dive deeper into error handling mechanisms and resolver optimization techniques. Remember, the best way to learn is by doing, so don't be afraid to get your hands dirty.

Looking forward, get ready for our next deep-dive - into GraphQL subscriptions and the WebSocket gateway. This exciting topic will take our real-time data handling capabilities to the next level, further expanding the possibilities of what we can achieve with GraphQL and Apollo Server. Stay tuned!

Creating a Simple Generator for Nx Plugins

Tanja Bayer — Tue, 30 May 2023 20:16:22 +0000

Introduction

Welcome to the second blog post in our series on creating custom Nx plugins! This post targets developers who are familiar with the basics of the Nx ecosystem but have never built a plugin for Nx before. In this article, we'll dive deep into generators, learn how to set up a development environment, and create a simple generator for an Nx plugin. Let's get started!

Deep Dive into Generators
Setting Up the Development Environment
Creating a Simple Generator
Working with the Nx Devkit Tree
Summary

Deep Dive into Generators

Nx Generators are an integral part of the Nx ecosystem, providing an interface for code generation and modification. They operate by reading and altering the Abstract Syntax Tree (AST) of your codebase, enabling precise and flexible modifications. This fine-grained control fosters creation of tailored development environments that reflect the unique needs of your project.

At its core, a generator is a function that accepts a Tree and an options object. The Tree represents your filesystem, and you interact with it to make file changes. The options object carries the values provided by the user when invoking the generator.

A fundamental concept in understanding Nx generators is their immutability. All changes you make to the Tree within a generator are staged, and not immediately applied. This staged approach allows changes to be grouped into an atomic commit, ensuring your filesystem stays in a consistent state even if the generator fails partway through execution.

To create a custom generator, you define a generator function in a file named generator.ts. The function receives a host Tree and an options object. For complex generators, Nx provides the generateFiles utility. This powerful utility employs schematics-like template syntax to interpolate variables into file contents and filenames.

For input control, Nx uses JSON Schema, allowing generators to accept complex inputs, validate them, and provide interactive prompts to the users. Defining a schema makes your generator self-documenting, as Nx can automatically generate descriptions, validations, and prompts based on it.

Generators can invoke other generators, allowing code reuse and composition. Nx provides helper functions like runTasksInSerial or runTasksInParallel to manage the lifecycle of these generator executions.

Testing generators is crucial, and Nx's virtual file system makes this easy. During tests, you can verify that the right changes are being applied without affecting your actual filesystem.

In conclusion, Nx Generators provide a powerful way to automate your development tasks, creating a robust, repeatable, and efficient development workflow.

Setting Up the Development Environment

Creating an Nx workspace and a custom plugin begins by using the create-nx-workspace utility. Let's create a new workspace named nx-tools.



npx create-nx-workspace@latest nx-tools

Select "empty" when prompted for a preset to create a bare workspace.

Now, incorporate the @nx/nx-plugin into your workspace. The @nx/nx-plugin furnishes essential tools for creating and managing Nx plugins.



nx add @nx/nx-plugin

With the Nx Plugin established, we'll now generate our custom plugin, named nx-cdk, in our workspace. This plugin will be designed to generate, build, and deploy AWS CDK projects, facilitating efficient development in our Nx monorepo.



nx g @nx/nx-plugin:plugin nx-cdk

This command creates a new plugin with the name nx-cdk and provides the preliminary code and configuration.

Finally, open your freshly created workspace in your preferred code editor. For Visual Studio Code users, this can be done with:



code nx-tools

With these steps completed, your development environment is primed for crafting your nx-cdk plugin.

Creating a Simple Generator for our nx-cdk Plugin

Now that the development environment for nx-tools is set up, we can begin with creating a simple generator for our nx-cdk plugin. The generator will help scaffold AWS CDK applications.

Nx Devkit provides a built-in schematic to help generate the boilerplate for our generator. Run the following command to create the generator:



nx g @nrwl/nx-plugin:generator NxCdk --project=nx-cdk

This command does several things:

It adds a new generator named nx-cdk in the nx-cdk plugin.
It creates a new nx-cdk directory inside the generators directory of our nx-cdk plugin.
Inside the generators/nx-cdk directory, it creates a generator.ts file which is the main file for our generator, a generator.spec.ts file which contains the test cases for our generator, a schema.json file which will be used to define the options for our generator and a schema.d.ts file containing the interface definition for our schema.

Open the schema.json and modify the content as per your requirements:



  "$schema": "http://json-schema.org/schema",
  "$id": "NxCdk",
  "title": "",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "",
      "$default": {
        "$source": "argv",
        "index": 0
      },
      "x-prompt": "What name would you like to use?"
    },
    "tags": {
      "type": "string",
      "description": "Add tags to the project (used for linting)",
      "alias": "t"
    },
    "directory": {
      "type": "string",
      "description": "A directory where the project is placed",
      "alias": "d"
    }
  },
  "required": [
    "name"
  ]
}

Next, update the generator.ts file with the code to scaffold a new AWS CDK project in your workspace:



import { readFileSync } from 'fs';
import * as path from 'path';
import { resolve } from 'path';

import {
    GeneratorCallback,
    Tree,
    addDependenciesToPackageJson,
    addProjectConfiguration,
    formatFiles,
    generateFiles,
    getWorkspaceLayout,
    names,
    offsetFromRoot
} from '@nx/devkit';
import { jestProjectGenerator } from '@nx/jest';
import { Linter, lintProjectGenerator } from '@nx/linter';
import { runTasksInSerial } from '@nx/workspace/src/utilities/run-tasks-in-serial';

import {
    awsCdkLibVersion,
    awsCdkVersion,
    constructsVersion,
    sourceMapSupportVersion,
    tsJestVersion
} from '../../utils/versions';
import { addJestPlugin } from './lib/add-jest-plugin';
import { addLinterPlugin } from './lib/add-linter-plugin';
import { NxCdkGeneratorSchema } from './schema';

interface NormalizedSchema extends NxCdkGeneratorSchema {
    projectName: string;
    projectRoot: string;
    projectDirectory: string;
    parsedTags: string[];
}

function normalizeOptions(tree: Tree, options: NxCdkGeneratorSchema): NormalizedSchema {
    const name = names(options.name).fileName;
    const projectDirectory = options.directory ? `${names(options.directory).fileName}/${name}` : name;
    const projectName = projectDirectory.replace(new RegExp('/', 'g'), '-');
    const projectRoot = `${getWorkspaceLayout(tree).appsDir}/${projectDirectory}`;
    const parsedTags = options.tags ? options.tags.split(',').map((s) => s.trim()) : [];

    return {
        ...options,
        projectName,
        projectRoot,
        projectDirectory,
        parsedTags
    };
}

function addFiles(tree: Tree, options: NormalizedSchema) {
    const templateOptions = {
        ...options,
        ...names(options.name),
        offsetFromRoot: offsetFromRoot(options.projectRoot),
        template: ''
    };
    generateFiles(tree, path.join(__dirname, 'files'), options.projectRoot, templateOptions);
}

export default async function (tree: Tree, options: NxCdkGeneratorSchema) {
    const tasks: GeneratorCallback[] = [];
    const normalizedOptions = normalizeOptions(tree, options);
    addProjectConfiguration(tree, normalizedOptions.projectName, {
        root: normalizedOptions.projectRoot,
        projectType: 'application',
        sourceRoot: `${normalizedOptions.projectRoot}/src`,
        targets: {
            bootstrap: {
                executor: '@myorg/nx-cdk:bootstrap'
            },
            deploy: {
                executor: '@myorg/nx-cdk:deploy'
            },
            destroy: {
                executor: '@myorg/nx-cdk:destroy'
            },
            diff: {
                executor: '@myorg/nx-cdk:diff'
            },
            ls: {
                executor: '@myorg/nx-cdk:ls'
            },
            synth: {
                executor: '@myorg/nx-cdk:synth'
            }
        },
        tags: normalizedOptions.parsedTags
    });
    addFiles(tree, normalizedOptions);
    tasks.push(addJestPlugin(tree));
    tasks.push(addLinterPlugin(tree));
    tasks.push(addDependencies(tree));
    await lintProjectGenerator(tree, { project: options.name, skipFormat: true, linter: Linter.EsLint });
    await jestProjectGenerator(tree, {
        project: options.name,
        setupFile: 'none',
        skipSerializers: true,
        testEnvironment: 'node'
    });
    await ignoreCdkOut(tree);
    await formatFiles(tree);
    return runTasksInSerial(...tasks);
}

function addDependencies(tree: Tree) {
    const dependencies: Record<string, string> = {};
    const devDependencies: Record<string, string> = {
        'aws-cdk': awsCdkVersion,
        'aws-cdk-lib': awsCdkLibVersion,
        constructs: constructsVersion,
        'source-map-support': sourceMapSupportVersion,
        'ts-jest': tsJestVersion
    };
    return addDependenciesToPackageJson(tree, dependencies, devDependencies);
}

async function ignoreCdkOut(tree: Tree) {
    const ignores = readFileSync(resolve(tree.root, '.gitignore'), { encoding: 'utf8' }).split('\n');
    if (!ignores.includes('cdk.out')) {
        ignores.push('# AWS CDK', 'cdk.out', '');
    }
    tree.write('./.gitignore', ignores.join('\n'));
}

Here's the explanation of what the generator.ts file does:

NormalizedSchema Interface: A TypeScript interface is defined that extends the NxCdkGeneratorSchema interface from schema.d.ts. It adds properties like projectName, projectRoot, projectDirectory, and parsedTags.
normalizeOptions Function: It accepts a Tree and generator options and returns the options after performing transformations like naming conventions, file path conventions, and tag parsing.
addFiles Function: This function generates files from the provided template and places them in the project directory.
The Main Generator Function: It's an async function that performs several tasks:
- Normalize the options using the normalizeOptions function.
- Add project configuration using the addProjectConfiguration function.
- Generate files using the addFiles function.
- Add Jest and Linter plugins to the Nx tree.
- Add dependencies to the package.json file using the addDependenciesToPackageJson function.
- Setup Jest and ESLint for the newly generated project.
- Ignore the cdk.out directory in .gitignore.
- Finally, format all the generated files. 5 addDependencies Function: Adds dependencies required for the AWS CDK project, like aws-cdk, aws-cdk-lib, constructs, source-map-support, and ts-jest to the devDependencies of package.json.
ignoreCdkOut Function: Reads the .gitignore file and checks if 'cdk.out' is included in the ignore list. If not, it adds 'cdk.out' to the list, which prevents the generated AWS CDK output files from being tracked by git.

The schema.d.ts file is where we define the TypeScript interface for our generator options. This interface helps TypeScript to understand the structure of the options and provide type checking. In our case, the interface for the NxCdkGeneratorSchema should look like this:



export interface NxCdkGeneratorSchema {
    name: string;
    tags?: string; 
    directory?: string; 
}

This TypeScript interface aligns with the schema.json file and provides a typed way of accessing the generator options.

Testing is a critical part of any software development, and Nx generators are not an exception. Nx provides a built-in way to test generators using Jest. When we created our NxCdk generator, Nx also created a generator.spec.ts file in the nx-cdk directory. This is a test specification file for our generator.



import { Tree } from '@nrwl/devkit';
import * as testingUtils from '../../../utils/testing';

import generator from './generator';
import { NxCdkGeneratorSchema } from './schema';

describe('myCdkApp generator', () => {
  let appTree: Tree;
  const options: NxCdkGeneratorSchema = { name: 'test' };

  beforeEach(() => {
    appTree = testingUtils.createEmptyWorkspace(Tree.empty());
  });

  it('should run successfully', async () => {
    await expect(
      generator(appTree, options)
    ).resolves.not.toThrowError();
  });
});

In this test case, we first create an empty Nx workspace. We then run our generator with a given set of options. The expect function is then used to assert that our generator should run without throwing any errors.

Working with the Nx Devkit Tree

The Nx Devkit Tree object represents the workspace's file system. It allows you to read, write, and manipulate files and directories. In our simple generator, we use the generateFiles function to create files from templates located in the ./files directory.

Registering the Generator



{

  "$schema": "http://json-schema.org/schema",

  "name": "nx-cdk",

  "version": "0.0.1",

  "generators": {

    "nx-cdk": {

      "factory": "./src/generators/nx-cdk/generator",

      "schema": "./src/generators/nx-cdk/schema.json",

      "description": "nx-cdk generator"

    }

  }

}

Summary

The blog post provides an in-depth guide on creating a simple generator for Nx plugins. It introduces the Nx ecosystem and the concept of generators, functions that manipulate your codebase via the Abstract Syntax Tree (AST). The key idea is the immutability of generators, where changes are staged and grouped into atomic commits for filesystem consistency.

The post presents a step-by-step tutorial on setting up an Nx workspace and crafting a custom Nx plugin. This involves creating a new workspace, incorporating the @nx/nx-plugin, generating a custom plugin, and opening the workspace in your code editor.

The main tutorial focuses on creating a generator for an nx-cdk plugin designed to generate, build, and deploy AWS CDK projects. This process includes running commands to create the generator, modifying the schema.json file to fit your requirements, and updating the generator.ts file with code to scaffold a new AWS CDK project.

Alright, you've made it this far and hopefully enjoyed the ride. The next stop on our journey will be implementing an executor. So grab some popcorn and stay tuned - I promise it will be just as fun, if not more! See you next time, folks!

Setting Up your Apollo Server with TypeGraphQL

Tanja Bayer — Tue, 16 May 2023 20:07:11 +0000

Welcome back to the second part of the Zero to Serverless Hero Series. In this blog post I will cover how you can configure your lambda to handle GraphQL queries.

If you are not yet familiar with how GraphQL works, I would recommend you to read the GraphQL Documentation.

Getting Started

For implementing the GraphQL schemas we will be using TypeGraphQL because this gives us an easy to understand and maintainable way to implement the GraphQL schema by using decorators. As of the time of writing the support for Apollo v4 version is still in beta, nevertheless, we will use the beta, because Apollo v3 is already deprecated. So let’s install it, along with the aws-lambda package which we will need npm i type-graphql@2.0.0-beta.1 aws-lambda. For building and deploying the lambda we will additionally install the following package as dev dependencies: npm i -D @cubesoft/nx-lambda-build depcheck.

Creating the Lambda Handler

In the last blog post we used inline code for our lambda handler. However, that should be only done only for testing or if you have pretty small functions, because you loose a lot of code maintainability there. So first we will put our lambda code into a separate file called serverless-api.ts.


 typescript
import { APIGatewayProxyEventV2, Context } from 'aws-lambda';

export async function handler(event: APIGatewayProxyEventV2, context: Context) {
  console.log('Hello, CDK!');
  return {
    statusCode: 200,
    body: JSON.stringify('Hello from Lambda!'),
  };
}

Then we need to tell the cdk how to find the code. Therefore, we need to change the lambda part in our stack (serverless-stack.ts):


 typescript
const lambda = new Function(this, 'api-handler', {
  runtime: Runtime.NODEJS_18_X,
  handler: 'serverless-api.handler',
  functionName: 'serverless-api',
  code: Code.fromAsset(
    join(
      getWorkspaceRoot(),
      'dist/packages/serverless-api/serverless-api',
      'handler.zip'
    )
  ),
  memorySize: Size.gibibytes(1).toMebibytes(),
  architecture: Architecture.ARM_64,
  logRetention: RetentionDays.ONE_DAY,
  timeout: Duration.seconds(5),
});

Additionally we also need to tell the nx-lambda-build plugin where our handler will be located. Therefore, we need to create a file called serverless-api/src/handlers.json to create a mapping between the handler name and the code location:



{
  "entrypoints": {
    "serverless-api": "src/handler/serverless-api"
  }
}

Before updating our lambda to be able to function as a GraphQL server, we first want to check if what we did so far is functioning. Because it is much easier to test smaller changes and fixing errors right after they occur, instead of searching for the problem in a whole stack of changes. For testing our lambda we first need to build it and then deploy it:


 bash
nx build serverless-api 
nx deploy serverless-cdk --profile <your-profile>

You need to confirm that you want to deploy the changes and afterwards you can check, that your /graphql endpoint still returns "Hello from Lambda!". If you go to your AWS Console and open your lambda function (Lambda > Functions > serverless-api), you will also see that your code is now deployed:

Configuring the Apollo Server

We need to install some dependency for using the Apollo server npm i -S typedi reflect-metadata @apollo/server graphql reflect-metadata @as-integrations/aws-lambda. After installing these dependencies we can start creating our first resolver, which we can later pass to our Apollo Server, which we will create in the next step.

We will stick with our easy lambda example and for the beginning and start with an easy query that will just return a message.


 typescript
import { Query, Resolver } from 'type-graphql';
import { Service } from 'typedi';

@Service()
@Resolver()
export class GreetingResolver {
  @Query(() => String, {
    description:
      'Returns a greeting message. This is a sample query that returns a string',
  })
  async hello(): Promise<string> {
    return 'world';
  }
}

Make sure to add both the @Resolver and the @Query decorator to your class. The @Resolver class is TypeGraphQL specific and is required to build the GraphQL schema from your implementation. The @Query decorator marks the class method as a GraphQL query.

After we have created our resolver we can create the Apollo Server and a build a GraphQL schema including our resolver. For this we replace the content of our serverless.api.ts file with the following code.


 typescript
import 'reflect-metadata';
import { ApolloServer } from '@apollo/server';
import 'graphql';
import { buildSchemaSync } from 'type-graphql';
import {
  handlers,
  startServerAndCreateLambdaHandler,
} from '@as-integrations/aws-lambda';
import { GreetingResolver } from '../resolver/greeting.resolver';

const schema = buildSchemaSync({
  resolvers: [GreetingResolver],
  validate: { forbidUnknownValues: false },
  dateScalarMode: 'timestamp',
});

const server = new ApolloServer({
  schema: schema,
  introspection: true,
  csrfPrevention: true,
});

export const handler = startServerAndCreateLambdaHandler(
  server,
  handlers.createAPIGatewayProxyEventV2RequestHandler()
);

As you can see we tell our schema to use our newly created resolver. Afterward this schema is injected into the Apollo Server and as a last part we create the handler to tell our lambda how to execute our calls.

Deploy your stack

Finally, you can build and deploy your CDK stack using the command nx build serverless-api && nx deploy serverless-cdk --profile serverless-hero. If you open your browser this time using the same url as last time (/graphql) you will no longer see the message "Hello from Lambda!" but you will see the apollo playground like in the image below. Now you have a GraphQL lambda hander, it only supports one simple query but this is a good starting point, isn’t it?

Next time we will setup a database for storing and retrieving data for your application.

You can find my sample repo here

Introduction to Nx Plugins and Nx Devkit

Tanja Bayer — Tue, 09 May 2023 20:42:41 +0000

Welcome to the first blog post in our series on creating custom Nx plugins! This post targets developers who are familiar with the basics of the Nx ecosystem but have never built a plugin for Nx before. In this article, we'll explore the importance of Nx plugins, introduce the Nx Devkit, and discuss the core concepts and basic structure of an Nx plugin. Let's dive in!

Why Nx Plugins Matter

Nx plugins play a crucial role in the Nx ecosystem, as they extend the functionality of an Nx workspace. By creating custom Nx plugins, developers can tailor the Nx experience to their specific project requirements, streamline workflows, and enhance productivity. Moreover, Nx plugins can be shared as npm packages or directly referenced within a single repo, allowing developers to leverage the power of the Nx community and build on the work of others.

The Nx Devkit

The Nx Devkit is the foundation for creating Nx plugins. It provides a simple and powerful API for creating generators and executors, which are the primary building blocks of Nx plugins. By using the Nx Devkit, developers can write custom code that seamlessly integrates with the underlying Nx core and benefits from its powerful features, such as computation caching and code generation.

Core Concepts of Nx Devkit

The Nx Devkit is based on a few core concepts:

Executors: Executors are responsible for running tasks within an Nx workspace. They define how a specific task should be executed, such as building, testing, or deploying an application.
Generators: Generators are responsible for generating code or modifying the workspace structure based on predefined templates and user input. They simplify repetitive tasks and enforce best practices.
Language Primitives and Immutable Objects: The Nx Devkit relies on language primitives and immutable objects, with the tree being the only exception. This simplicity makes the Devkit easy to understand and work with.

The Nx Devkit offers a set of core APIs and utilities to help developers get started with their plugin:

Tree: An in-memory file system representation that allows for manipulating files and directories in the workspace. It is used by generators to make changes to the workspace.
ProjectConfiguration: A utility for managing project configuration in an Nx workspace.
runExecutor: A function for running executors programmatically, useful for testing.
readJson: A utility for reading JSON files in the workspace.
writeJson: A utility for writing JSON files in the workspace.
generateFiles: A utility for generating files from templates.

These tools make it easier for developers to create and test Nx plugins while ensuring compatibility with the Nx ecosystem.

The Basic Structure of an Nx Plugin

An Nx plugin consists of the following main components:

executors.json: This file registers executors in the plugin.
generators.json: This file registers generators in the plugin.
src/: This directory contains the source code for the plugin's executors and generators.
package.json: Contains references to the generators and executors schematics.

Example of a simple package.json:



{

  "name": "@org/my-custom-plugin",

  "version": "1.0.0",

  "main": "src/index.js",

  "generators": "./generators.json",

  "executors": "./executors.json",

  "devDependencies": {

    ...

  },

  "peerDependencies": {

    ...

  }

}

Summary

In this introductory blog post, we've covered the importance of Nx plugins, introduced the Nx Devkit, and discussed the core concepts of the Nx Devkit. We also looked at the basic structure of an Nx plugin. In the next blog post, we'll dive deeper into generators and guide you through creating a simple generator step by step. Stay tuned!

Setting Up Your Environment for a Serverless GraphQL API on AWS Lambda

Tanja Bayer — Tue, 02 May 2023 16:00:00 +0000

Serverless is cool and can save you a lot of money, because you do not have servers running all the time, only when someone wants to use your service - an that is also good for our environment, isn't it? But when you want to start with serverless the amount of documentation might be really overwhelming and you might not know where to start. This blog posts series should help you getting an easy entry into the topic. It will cover the process of constructing a fully serverless GraphQL API, which will include queries, mutations, and subscriptions. The deployment of this API will be accomplished through the use of the AWS CDK.

In this first part we will do the initial setup using the AWS CDK and build an initial version with the AWS Api Gateway and AWS Lambda.

Getting Started

First of all we will be doing everything as code so that it can be reused and easily adapted to future needs. We assume you already have an AWS account and setup your AWS CLI with your credentials. If you did not do this yet, create a account following the AWS User Guide and setup your CLI following the Getting started with the AWS CLI and the user guide on Configuration and credential file settings.

So lets start setting up our project and creating our lambda function with the CDK.

Create a Workspace and your Project

First things first, setup the repo. We will be using nx to create a monorepo to have all our code in one place. Run npx create-nx-workspace@latest serverless-hero --preset=ts and follow the steps and confirm the request to install the necessary packages. Now we have our repo let's setup our package: npm i @nx/node && nx g @nx/node:application serverless-api. When nx asks you which framework to install choose none.

Install the AWS CDK

For being able to use the CDK we first need to install it, for this run npm i -D aws-cdk-lib in the root of your newly created project.

Create the CDK App

For creating our cdk app as an nx package we will use the nx-cdk package. First install the package with npm i -D @nrwl/workspace && npm i -D @cubesoft/nx-cdk and then you can create your cdk app with nx g @cubesoft/nx-cdk:nx-cdk serverless-cdk. This creates a new package called serverless-cdk for us, for finishing the setup we need to provide the correct environment values in the serverless-cdk/src/app.ts file for account and region. And make sure the line in which you put it is uncommented. Then we need to run nx bootstrap serverless-cdk --profile <profile> (the profile parameter is only required if you have multiple profiles in your aws credentials file) and we are ready to go.

Defining the CDK Stack

Now that we have setup everything we can start with the interesting stuff. Let's have a quick look an what we want to achieve.

So there are two main parts we need to setup:

The API Gateway
The Lambda Function

The API Gateway

Let's start with the fun part, setting up the API Gateway
We will create a HTTP API because this comes at lower costs than the REST API, and we do not need the additional features of the REST API however if you are interested in the differences between both you can read more here.

In the serverless-cdk/src/lib/my-stack.ts you can add the add the HttpApi with the required configurations. Btw. you can also rename the my-stack file and the name of the Stack itself, I renamed it to ServerlessStack, but make sure you correctly reference it in your app.ts file.

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

import { CorsHttpMethod, HttpApi } from '@aws-cdk/aws-apigatewayv2-alpha';
export class ServerlessStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const api = new HttpApi(this, 'httpAPI', {
      apiName: `http-api`,
      corsPreflight: {
        allowHeaders: ['Content-Type', 'Authorization'],
        allowMethods: [CorsHttpMethod.GET, CorsHttpMethod.POST],
        allowOrigins: ['*'],
      },
    });
  }
}

Make sure to install the @aws-cdk/aws-apigatewayv2-alpha package.

To ensure that the API can later be called via a browser we need to provide the corsPreflight options, because we also want to also add authorisation functionality later we provide a specific 'Authorization' header, but you can add even more if you need them.

The Lambda Function

Now that we have the Gateway we can create the Lambda function. For this blog post we will create a really simple Lambda Function and we will focus on the GraphQL part in the next blog post.

import { Duration, Size } from 'aws-cdk-lib';
import { Architecture, Code, Function, Runtime } from 'aws-cdk-lib/aws-lambda';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';

const lambda = new Function(this,'api-handler', {
    runtime: Runtime.NODEJS_18_X,
    handler: 'handler',
      code: lambda.Code.fromInline(`
    exports.handler = async function(event) {
      console.log("Hello, CDK!");
      return {
        statusCode: 200,
        body: JSON.stringify('Hello from Lambda!'),
      };
    }
  `),
    memorySize: Size.gibibytes(1).toMebibytes(),
    architecture: Architecture.ARM_64,
    logRetention: RetentionDays.ONE_MONTH,
    timeout: Duration.seconds(5)
});

This creates the Lambda Function, now we need to connect it with the API Gateway, so that someone can call it. For this you need to install @aws-cdk/aws-apigatewayv2-integrations-alpha

import { HttpApi, HttpMethod } from '@aws-cdk/aws-apigatewayv2-alpha';
import { HttpLambdaIntegration } from '@aws-cdk/aws-apigatewayv2-integrations-alpha';

const readIntegration = new HttpLambdaIntegration('apiReadIntegration', lambda);
const writeIntegration = new HttpLambdaIntegration('apiWriteIntegration', lambda);

api.addRoutes({
   integration: readIntegration,
   methods: [HttpMethod.GET],
   path: '/graphql'
});
api.addRoutes({
   integration: writeIntegration,
   methods: [HttpMethod.POST],
   path: '/graphql'
});

Deploy your stack

Finally, you can deploy your CDK stack using the command nx deploy serverless-cdk. And there you are, you have just created and deployed your first lambda function on AWS. When you visit your AWS Console and go to the AWS API Gateway you can find your invoke url which you can use to check if your deployed api works. Just open it in your browser /graphql and you should see the text "Hello from Lambda!". You made it!

You can find my sample repo here

Forem: Tanja Bayer

Vector Search Demystified: A Guide to pgvector, IVFFlat, and HNSW

Vector Databases: The Engine Behind Modern AI Applications

The Rise of Vector Search: More Than Just Keywords

What Makes Vector Databases Special?

The Technical Foundation: Vector Embeddings

Choosing Your Vector Index: IVFFlat vs. HNSW

IVFFlat: The Efficient Workhorse

HNSW: The Speed Demon

Real-World Decision Matrix

Performance in Numbers

Best Practices & Implementation Tips

Looking Forward: The Future of Vector Search

Next Steps

How to Set Up a GitHub Actions Self-Hosted Runner on macOS 15+

Introduction

General Setup of a Self-Hosted Runner

Adding a Self-Hosted Runner to Your Organization

Verifying the Runner

Configuring the Runner as a Service on macOS 15+

Installing the Service

Stop the Runner Application:

Install the Service

Starting the Service

Checking the Service Status

Stopping and Uninstalling the Service

Uninstall the Service

Prioritizing Self-Hosted Runners in Workflows

Explanation

Check-Runner Job

Your-Job :

Setting Up Organization Secrets

Create an Access Token :

Add the Token to Organization Secrets :

Common Pitfalls and Solutions

1. Permission Issues with Installing the Service

Problem:

Solution:

2. Runner Not Showing as "Online"

Problem :

Solution :

Conclusion

Key takeaways:

Mastering Angular SSR: Enabling Custom HTTP Responses (404, 301)

Why is This Important?

Search Engine Understanding:

Crawl Efficiency:

Improved User Experience:

Implementation Details

1. Soft 404 Component

2. Create a Response Token

3. 301 Redirect Component

4. Update server.ts

Trouble Shooting

Final Thoughts

Mastering Log Retrieval in ECS Services: From Initial Trials to Advanced Solutions

The Problem

The First Approach

A Better Approach

Implementation Details

Configuring the Logs for the Firelens Container

FireLens Log Driver Setup

Task Definition for the Application Container

Custom FireLens Image

Fluent Bit Configuration: logConfig.conf

Adaptions to Dockerfile used in Service

Repository Creation and Docker Image Deployment

FireLens Log Router Configuration

Permission Policy for CloudWatch Logs

Conclusion

Securing Your Serverless GraphQL API - Part III

Table of Contents

Creating Custom Scopes

Restricting Access Bases on Scopes

Conclusion

Securing Your Serverless GraphQL API - Part II

Table of Contents

AWS Cognito: The Perfect Tool for User Authentication and Setting It Up

Setting Up Authorization for Secured Data Access

Conclusion