@yandex-cloud/serverless-live-debug
TypeScript icon, indicating that this package has built-in type declarations

1.3.0 • Public • Published

Serverless Live Debug

Live debug of Yandex Cloud Functions in Node.js.

How it works

diagram

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!`,
        };
      })
    });
    Or `live-debug.config.js` (cjs):
    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

Readme

Keywords

none

Package Sidebar

Install

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

Weekly Downloads

3

Version

1.3.0

License

Apache License 2.0

Unpacked Size

33.7 MB

Total Files

11

Last publish

Collaborators

  • yc-ui-bot
  • seqvirioum
  • resure
  • amje
  • yandex-cloud-bot
  • monsterzz