Running sidecar lambdas locally

[benmag]

First off just want to say, sidecar is awesome!

I wanted to quickly share how I am running sidecar/lambdas for my local development in case it's of use to anyone else in the future.

1. Install AWS SAM CLI

AWS SAM CLI lets us emulate AWS serverless functions right on our local machine. Install the AWS SAM CLI by following the instructions in the link below:

• https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html#install-sam-cli-instructions

2. Create a SAM template.yaml

In your Lambda function folder (for instance, /resources/lambda), create a template.yaml file. This file tells AWS SAM how to handle the Lambda function locally. Here's a simple example, you can add additional functions as required:

AWSTemplateFormatVersion: 2010-09-09
Description: >-
  sc-local
Transform:
  - AWS::Serverless-2016-10-31
Resources:
  MyFunctionName:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: 'sc-app-local-function-name:active' # Replace this with your function name in AWS. Make sure you append :active
      Handler: index.myFunctionName
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      MemorySize: 512
      Timeout: 30

3. Run Lambda Functions Locally

Now comes the exciting part! From within your /resources/lambda directory, run the following command to start your Lambda functions locally:

sam local start-lambda

This command fires up the local Lambda environment, allowing you to test your functions without the need to deploy them to AWS or have an internet connection.

4. Configure a Custom Service Provider

To customize certain aspects of the Sidecar package specifically for local development, we'll need to override a few classes.

Create the following files in your app

Services/Sidecar/AwsClientConfiguration.php

<?php

namespace App\Services\Sidecar;

// Override the AWS config to set the endpoint. If you are using Laravel Sail you will need to use `host.docker.internal` to access the `localhost` on your machine
class AwsClientConfiguration {
    public function getConfiguration()
    {
        $config = (new \Hammerstone\Sidecar\Clients\Configurations\AwsClientConfiguration())->getConfiguration();
        $config['endpoint'] = 'http://host.docker.internal:3001';
        return $config;
    }
}

Services/Sidecar/LambdaClient.php

<?php

namespace App\Services\Sidecar;

use Aws\Result;

// We need to override the `LogType` param. Local lambda only supports `None`
class LambdaClient extends \Hammerstone\Sidecar\Clients\LambdaClient {
    public function invoke(array $args = []): Result
    {
        $args['LogType'] = 'None';
        return parent::invoke($args);
    }
}

We'll use a custom service provider to ensure these classes are used only during local development. Create the following file:

app/Providers/SidecarServiceProvider.php

<?php

namespace App\Providers;

use App\Services\Sidecar\AwsClientConfiguration as CustomSidecarAwsClientConfiguration;
use App\Services\Sidecar\LambdaClient as CustomSidecarLambdaClient;
use Hammerstone\Sidecar\Clients\LambdaClient;
use Hammerstone\Sidecar\Contracts\AwsClientConfiguration as AwsClientConfigurationContract;

class SidecarServiceProvider extends \Hammerstone\Sidecar\Providers\SidecarServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        if (app()->environment('local')) {
            $this->app->singleton(LambdaClient::class, function () {
                return new CustomSidecarLambdaClient($this->getAwsClientConfiguration());
            });

            $this->app->bind(AwsClientConfigurationContract::class, CustomSidecarAwsClientConfiguration::class);
        }
    }
}

5. Add the New Service Provider

Finally, make use of the custom service provider. Inside your config/app.php file, locate the 'providers' array, and add the following line:

'providers' => [
    // ...other providers
    App\Providers\SidecarServiceProvider::class,
],

That's it!

Now you can run your Sidecar/Lambda functions locally!