Serverless Live Debug

Live debug of Yandex Cloud Functions in Node.js.

• How it works
• Setup
• Usage
  • Debug single function
  • Debug several functions
  • Debug other triggers
• Watch
• Cleanup

How it works

Main components:

1. stub - cloud function that proxies requests to local code
2. store - cloud function that stores WebSocket connections info in YDB. This connection info is later used by stub to know where to proxy request
3. client - CLI app running on local machine and handling requests coming by WebSocket

The schema was inspired by SST Live Lambda Dev

Setup

Ensure that you have Terraform installed.

1. Install package:

   npm i -D @yandex-cloud/serverless-live-debug

2. Deploy cloud components:

   npx serverless-live-debug deploy

   Review terraform plan and press Approve.

   By default this command uses yc cli to get auth token and cloud id. You can manually set these values by YC_TOKEN and YC_CLOUD_ID env vars

   To authorize by service account key use YC_SERVICE_ACCOUNT_KEY_FILE env var:

   YC_SERVICE_ACCOUNT_KEY_FILE=path/to/key.json npx serverless-live-debug deploy

   By default all components will be created in separate cloud catalogue live-debug. You can change this name using LIVE_DEBUG_FOLDER_NAME env var:

   LIVE_DEBUG_FOLDER_NAME=live-debug-test npx serverless-live-debug deploy

3. Create live-debug.config.ts in project root:

   import { defineConfig } from '@yandex-cloud/serverless-live-debug';
   import { Handler } from '@yandex-cloud/function-types';
   
   export default defineConfig({
     handler: <Handler.Http>(event => {
       console.log('got request', event);
       return {
         statusCode: 200,
         body: `Hello from local code!`,
       };
     })
   });

   const { defineConfig } = require('@yandex-cloud/serverless-live-debug');
   
   module.exports = defineConfig({
     handler: event => {
       console.log('got request', event);
       return {
         statusCode: 200,
         body: `Hello from local code!`,
       };
     }
   });

4. Run live debug:

   npx serverless-live-debug run

   Expected output:

   Using config: live-debug.config.ts
   Running local client...
   Starting child...
   Child started
   Watching changes in: live-debug.config.ts
   WS connection opened
   Local client ready.
   Check url: https://**********.apigw.yandexcloud.net
   Waiting requests...
   GET /?
   Response sent

   Click provided link and check console.

See example for more details.

Don't forget to add .live-debug dir to .gitignore

Usage

All requests to cloud stub function will come to local handler. Inside handler you can setup any routing for your needs.

Debug single function

To debug single function you can just assign handler in config:

import { defineConfig } from '@yandex-cloud/serverless-live-debug';
import { handler } from './path/to/your/handler';

export default defineConfig({
  handler
});

Debug several functions

To debug several functions you can setup routing inside handler (for example by url):

import { defineConfig } from '@yandex-cloud/serverless-live-debug';
import { Handler } from '@yandex-cloud/function-types';
import { handlerA } from './path/to/your/handler-a';
import { handlerB } from './path/to/your/handler-b';

export default defineConfig({
  handler: <Handler.Http>((event, ctx) => {
    // @ts-expect-error url is not typed
    const url = String(event.url);
    if (url.startsWith('/handler-a')) return handlerA(event, ctx);
    if (url.startsWith('/handler-b')) return handlerB(event, ctx);
    return { statusCode: 200, body: 'No handler' };
  })
});

Debug other triggers

You can debug all other triggers: message queue, object storage, etc. In cloud console configure needed trigger to point to stub function.

import { defineConfig } from '@yandex-cloud/serverless-live-debug';
import { Handler } from '@yandex-cloud/function-types';

export default defineConfig({
  handler: <Handler.MessageQueue>(event => {
    console.log(event.messages);
  })
});

Watch

By default, process watches changes in live-debug.config.ts and updates handler. You can set watch key in config to watch additional files and directories:

import { defineConfig } from '@yandex-cloud/serverless-live-debug';

export default defineConfig({
  watch: 'src',
  handler: ...
});

Cleanup

To destroy all live-debug resources in cloud run the following command:

npx serverless-live-debug destroy